<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="UTF-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="version" content="0.17"/>
  <meta name="subject" content="build system"/>
  <meta name="title" content="Build System"/>
  <meta name="copyright" content="2014-2024 the build2 authors"/>

  <title>The build2 Build System</title>

  <style type="text/css">
/* file      : common.css
 * license   : MIT; see accompanying LICENSE file
 */

html
{
  font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif;
  font-weight: normal;
  font-size: 18px;
  line-height: 1.4em;
  letter-spacing: 0.01em;

  color: #292929;
}

body {margin: 0;} /* There is non-0 default margin for body. */

/* See notes on what's going on here. */
body {min-width: 17em;}
@media only screen and (min-width: 360px)
{
  body {min-width: 19em;}
}

/*
 * Header (optional).
 */

#header-bar
{
  width: 100%;

  background: rgba(0, 0, 0, 0.04);
  border-bottom: 1px solid rgba(0, 0, 0, 0.2);

  padding: .4em 0 .42em 0;
  margin: 0 0 1.4em 0;
}

#header
{
  /* Same as in #content. */
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em;

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;

  width: 100%;
  display: table;
  border: none;
  border-collapse: collapse;
}

#header-logo, #header-menu
{
  display: table-cell;
  border: none;
  padding: 0;
  vertical-align: middle;
}

#header-logo {text-align: left;}
#header-menu {text-align: right;}

/* These overlap with #header's margin because of border collapsing. */
#header-logo {padding-left: .4em;}
#header-menu {padding-right: .4em;}

#header-logo a
{
  color: #000;
  text-decoration: none;
  outline: none;
}
#header-logo a:visited {color: #000;}
#header-logo a:hover, #header-logo a:active {color: #000;}

#header-menu a
{
  font-size: 0.889em;
  line-height: 1.4em;
  text-align: right;
  margin-left: 1.2em;
  white-space: nowrap;
  letter-spacing: 0;
}

#header-menu a
{
  color: #000;
  outline: none;
}
#header-menu a:visited {color: #000;}
#header-menu a:hover, #header-menu a:active
{
  color: #3870c0;
  text-decoration: none;
}

/* Flexbox-based improvements though the above works reasonably well. */
#header-menu-body
{
  width: 100%;

  display: -webkit-inline-flex;
  display: inline-flex;

  -webkit-flex-flow: row wrap;
  flex-flow: row wrap;

  -webkit-justify-content: flex-end;
  justify-content: flex-end;
}

/* Whether we want it (and at which point) depends on the size of the menu. */
/*
@media only screen and (max-width: 567px)
{
  #header-menu-body
  {
    -webkit-flex-direction: column;
    flex-direction: column;
  }
}
*/

/*
 * Content.
 */

#content
{
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em; /* Space between text and browser frame. */

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

/*
 * Footer (optional).
 */

#footer
{
  color: #767676;
  font-size: 0.7223em;
  line-height: 1.3em;
  margin: 2.2em 0 1em 0;
  text-align: center;
}

#footer a
{
  color: #767676;
  text-decoration: underline;
}
#footer a:visited {color: #767676;}
#footer a:hover, #footer a:active {color: #3870c0;}

/* Screen size indicator in the footer. The before/after content is in case
   we don't have any content in the footer. Margin is to actually see the
   border separate from the browser frame. */

/*
#footer:before {content: "\A0";}
#footer:after {content: "\A0";}

#footer
{
  border-left: 1px solid;
  border-right: 1px solid;
  margin-left: 1px;
  margin-right: 1px;
}

@media only screen and (max-width: 359px)
{
  #footer {border-color: red;}
}

@media only screen and (min-width: 360px) and (max-width: 567px)
{
  #footer {border-color: orange;}
}

@media only screen and (min-width: 568px) and (max-width: 1023px)
{
  #footer {border-color: blue;}
}

@media only screen and (min-width: 1024px)
{
  #footer {border-color: green;}
}
*/

/*
 * Common elements.
 */

p, li, dd {text-align: justify;}
.code {text-align: left;} /* Manually aligned. */
pre {text-align: left;}   /* If it is inside li/dd. */

/* Notes. */

.note
{
  color: #606060;
}

div.note
{
  margin: 2em 0 2em 0; /* The same top/bottom margings as pre box. */

  padding-left: 0.5em;
  border: 0.25em;
  border-left-style: solid;
  border-color: #808080;

  page-break-inside: avoid;
}

div.note :first-child {margin-top:    0;}
div.note :last-child  {margin-bottom: 0;}

span.note::before {content: "[Note: "}
span.note::after  {content: "]"}

/* Links. */
a
{
  color: #3870c0;
  /*color: #4078c0;*/
  text-decoration: none;
}

a:hover, a:active
{
/*color: #006fbf;*/
/*color: #0087e7;*/
  text-decoration: underline;
}

a:visited
{
/*color: #003388;*/
  color: #00409c;
}

/* Standard paragraph. */

p, pre {margin: 1em 0 1em 0;}

/* Standard lists. */
ul, ol, dl {margin: 1em 0 1em 0;}
ul li, ol li {margin: 0 0 .4em 0;}
ul li {list-style-type: circle;}
dl dt {margin: 0 0 0 0;}
dl dd {margin: 0 0 .6em 1.8em;}

code, pre
{
  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
  font-size: 0.92em;
  letter-spacing: 0;
}

pre {white-space: pre-wrap;}
@media only screen and (max-width: 567px)
{
  pre {word-break: break-all;}
}

/* Use page rather than system font settings. */
input
{
  font-family: inherit;
  font-weight: inherit;
  font-size:   inherit;
  line-height: inherit;
}

/* file      : pre-box.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Note: see also p-code-box.css. */

pre
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .8em .4em .8em .4em;
  margin: 2em -.4em 2em -.4em; /* Use margins of #content. */
}

/* file      : code-box.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Note: see also p-code-box.css if changing anything here. */

code
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .2em .32em .18em .32em;
}

/* file      : toc.css
 * license   : MIT; see accompanying LICENSE file
 */

table.toc
{
  border-style      : none;
  border-collapse   : separate;
  border-spacing    : 0;

  margin            : 0.2em 0 0.2em 0;
  padding           : 0 0 0 0;
}

table.toc tr
{
  padding           : 0 0 0 0;
  margin            : 0 0 0 0;
}

table.toc * td, table.toc * th {
  border-style      : none;
  margin            : 0 0 0 0;
  vertical-align    : top;
}

table.toc * th
{
  font-weight       : normal;
  padding           : 0 0.8em 0 0;
  text-align        : left;
  white-space       : nowrap;
}

table.toc * table.toc th
{
  padding-left      : 1em;
}

table.toc * td
{
  padding           : 0 0 0 0;
  text-align        : left;
}

table.toc * td.preface
{
  padding-left      : 1.35em;
}

/* file      : intro.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Bases:
 *
 * common.css
 * pre-box.css
 * code-box.css
 *
 */

#content
{
  max-width: 43.6em;
  padding-left: 3em; /* Reserve for headings. */
}

h1
{
  font-weight: normal;
  font-size: 2em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -1.4em;
}

h1.preface
{
  margin-left: -.56em;
}

h2
{
  font-weight: normal;
  font-size: 1.556em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -.8em;
}

h3
{
  font-weight: normal;
  font-size: 1.3em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -.2em;
}

/* Title page */

#titlepage {
  margin: 0 0 4em 0;
  border-bottom: 1px solid black;
}

#titlepage .title {
  font-weight: normal;
  font-size: 2.333em;
  line-height: 1.4em;
  letter-spacing: 0;
  text-align: center;
  margin: 2em 0 2em 0;
}

#titlepage p {
  font-size: 0.889em;
  line-height: 1.4em;
  margin: 2em 0 .6em 0;
}

  </style>

</head>
<body>
<div id="content">

  <div class="noprint"> <!-- Exclude from html2ps. -->

  <div id="titlepage">
    <div class="title">The <code>build2</code> Build System</div>

    <p id="revision">Revision <code>0.17</code>, May 2024<br/>
    This revision of the document describes the <a href="https://build2.org"><code>build2</code></a>
    build system <code>0.17.X</code> series and is available in the
    following formats:
    <a href="build2-build-system-manual.xhtml">XHTML</a>,
    <a href="build2-build-system-manual-a4.pdf">PDF/A4</a>,
    <a href="build2-build-system-manual-letter.pdf">PDF/Letter</a>,
    <a href="build2-build-system-manual-a4.ps">PostScript/A4</a>, and
    <a href="build2-build-system-manual-letter.ps">PostScript/Letter</a>.</p>

    <p>Copyright &#169; 2014-2024 the build2 authors.<br/>
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the MIT License.</p>
  </div>

  <h1>Table of Contents</h1>

  <table class="toc">
    <tr><td class="preface" colspan="2"><a
href="#preface">Preface</a></td></tr>
    <tr><th>1</th><td><a href="#intro">Introduction</a>
      <table class="toc">
        <tr><th>1.1</th><td><a href="#intro-hello">Hello, World</a></td></tr>
        <tr><th>1.2</th><td><a href="#intro-proj-struct">Project
Structure</a></td></tr>
        <tr><th>1.3</th><td><a href="#intro-dirs-scopes">Output Directories
and Scopes</a></td></tr>
        <tr><th>1.4</th><td><a href="#intro-operations">Operations</a>
          <table class="toc">
            <tr><th>1.4.1</th><td><a
href="#intro-operations-config">Configuring</a></td></tr>
            <tr><th>1.4.2</th><td><a
href="#intro-operations-test">Testing</a></td></tr>
            <tr><th>1.4.3</th><td><a
href="#intro-operations-install">Installing</a></td></tr>
            <tr><th>1.4.4</th><td><a
href="#intro-operations-dist">Distributing</a></td></tr>
          </table>
        </td></tr>
        <tr><th>1.5</th><td><a href="#intro-import">Target
Importation</a></td></tr>
        <tr><th>1.6</th><td><a href="#intro-lib">Library Exportation and
Versioning</a></td></tr>
        <tr><th>1.7</th><td><a href="#intro-subproj">Subprojects and
Amalgamations</a></td></tr>
        <tr><th>1.8</th><td><a href="#intro-lang">Buildfile Language</a>
          <table class="toc">
            <tr><th>1.8.1</th><td><a href="#intro-lang-expand">Expansion and
Quoting</a></td></tr>
            <tr><th>1.8.2</th><td><a href="#intro-if-else">Conditions
(<code>if-else</code>)</a></td></tr>
            <tr><th>1.8.3</th><td><a href="#intro-switch">Pattern Matching
(<code>switch</code>)</a></td></tr>
            <tr><th>1.8.4</th><td><a href="#intro-for">Repetitions
(<code>for</code>)</a></td></tr>
          </table>
        </td></tr>
        <tr><th>1.9</th><td><a href="#intro-unit-test">Implementing Unit
Testing</a></td></tr>
        <tr><th>1.10</th><td><a href="#intro-diag-debug">Diagnostics and
Debugging</a></td></tr>
      </table>
    </td></tr>
    <tr><th>2</th><td><a href="#proj-config">Project Configuration</a>
      <table class="toc">
        <tr><th>2.1</th><td><a
href="#proj-config-directive"><code>config</code> Directive</a></td></tr>
        <tr><th>2.2</th><td><a href="#proj-config-report">Configuration
Report</a></td></tr>
        <tr><th>2.3</th><td><a href="#proj-config-propag">Configuration
Propagation</a></td></tr>
      </table>
    </td></tr>
    <tr><th>3</th><td><a href="#targets">Targets and Target Types</a>
      <table class="toc">
        <tr><th>3.1</th><td><a href="#targets-types">Target Types</a>
          <table class="toc">
            <tr><th>3.1.1</th><td><a
href="#targets-types-target"><code>target{}</code></a></td></tr>
            <tr><th>3.1.2</th><td><a
href="#targets-types-alias"><code>alias{}</code> and
<code>dir{}</code></a></td></tr>
            <tr><th>3.1.3</th><td><a
href="#targets-types-fsdir"><code>fsdir{}</code></a></td></tr>
            <tr><th>3.1.4</th><td><a
href="#targets-types-mtime-path"><code>mtime_target{}</code> and
<code>path_target{}</code></a></td></tr>
            <tr><th>3.1.5</th><td><a
href="#targets-types-group"><code>group{}</code></a></td></tr>
            <tr><th>3.1.6</th><td><a
href="#targets-types-file"><code>file{}</code></a></td></tr>
            <tr><th>3.1.7</th><td><a
href="#targets-types-doc"><code>doc{}</code>, <code>legal{}</code>, and
<code>man{}</code></a></td></tr>
            <tr><th>3.1.8</th><td><a
href="#targets-types-exe"><code>exe{}</code></a></td></tr>
          </table>
        </td></tr>
      </table>
    </td></tr>
    <tr><th>4</th><td><a href="#variables">Variables</a></td></tr>
    <tr><th>5</th><td><a href="#functions">Functions</a>
      <table class="toc">
        <tr><th>5.1</th><td><a href="#functions-builtin">Builtin Functions</a>
          <table class="toc">
            <tr><th>5.1.1</th><td><a
href="#functions-builtin-defined"><code>$builtin.defined()</code></a></td></tr>
            <tr><th>5.1.2</th><td><a
href="#functions-builtin-visibility"><code>$builtin.visibility()</code></a></td></tr>
            <tr><th>5.1.3</th><td><a
href="#functions-builtin-type"><code>$builtin.type()</code></a></td></tr>
            <tr><th>5.1.4</th><td><a
href="#functions-builtin-null"><code>$builtin.null()</code></a></td></tr>
            <tr><th>5.1.5</th><td><a
href="#functions-builtin-empty"><code>$builtin.empty()</code></a></td></tr>
            <tr><th>5.1.6</th><td><a
href="#functions-builtin-first"><code>$builtin.first()</code>,
<code>$builtin.second()</code></a></td></tr>
            <tr><th>5.1.7</th><td><a
href="#functions-builtin-quote"><code>$builtin.quote()</code></a></td></tr>
            <tr><th>5.1.8</th><td><a
href="#functions-builtin-getenv"><code>$builtin.getenv()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.2</th><td><a href="#functions-string">String Functions</a>
          <table class="toc">
            <tr><th>5.2.1</th><td><a
href="#functions-string-icasecmp"><code>$string.icasecmp()</code></a></td></tr>
            <tr><th>5.2.2</th><td><a
href="#functions-string-contains"><code>$string.contains()</code></a></td></tr>
            <tr><th>5.2.3</th><td><a
href="#functions-string-starts_with"><code>$string.starts_with()</code></a></td></tr>
            <tr><th>5.2.4</th><td><a
href="#functions-string-ends_with"><code>$string.ends_with()</code></a></td></tr>
            <tr><th>5.2.5</th><td><a
href="#functions-string-replace"><code>$string.replace()</code></a></td></tr>
            <tr><th>5.2.6</th><td><a
href="#functions-string-trim"><code>$string.trim()</code></a></td></tr>
            <tr><th>5.2.7</th><td><a
href="#functions-string-lcase"><code>$string.lcase()</code>,
<code>$string.ucase()</code></a></td></tr>
            <tr><th>5.2.8</th><td><a
href="#functions-string-size"><code>$string.size()</code></a></td></tr>
            <tr><th>5.2.9</th><td><a
href="#functions-string-sort"><code>$string.sort()</code></a></td></tr>
            <tr><th>5.2.10</th><td><a
href="#functions-string-find"><code>$string.find()</code></a></td></tr>
            <tr><th>5.2.11</th><td><a
href="#functions-string-find_index"><code>$string.find_index()</code></a></td></tr>
            <tr><th>5.2.12</th><td><a
href="#functions-string-keys"><code>$string.keys()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.3</th><td><a href="#functions-integer">Integer Functions</a>
          <table class="toc">
            <tr><th>5.3.1</th><td><a
href="#functions-integer-string"><code>$integer.string()</code></a></td></tr>
            <tr><th>5.3.2</th><td><a
href="#functions-integer-integer_sequence"><code>$integer.integer_sequence()</code></a></td></tr>
            <tr><th>5.3.3</th><td><a
href="#functions-integer-size"><code>$integer.size()</code></a></td></tr>
            <tr><th>5.3.4</th><td><a
href="#functions-integer-sort"><code>$integer.sort()</code></a></td></tr>
            <tr><th>5.3.5</th><td><a
href="#functions-integer-find"><code>$integer.find()</code></a></td></tr>
            <tr><th>5.3.6</th><td><a
href="#functions-integer-find_index"><code>$integer.find_index()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.4</th><td><a href="#functions-bool">Bool Functions</a>
          <table class="toc">
            <tr><th>5.4.1</th><td><a
href="#functions-bool-string"><code>$bool.string()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.5</th><td><a href="#functions-path">Path Functions</a>
          <table class="toc">
            <tr><th>5.5.1</th><td><a
href="#functions-path-string"><code>$path.string()</code></a></td></tr>
            <tr><th>5.5.2</th><td><a
href="#functions-path-posix_string"><code>$path.posix_string()</code></a></td></tr>
            <tr><th>5.5.3</th><td><a
href="#functions-path-representation"><code>$path.representation()</code></a></td></tr>
            <tr><th>5.5.4</th><td><a
href="#functions-path-posix_representation"><code>$path.posix_representation()</code></a></td></tr>
            <tr><th>5.5.5</th><td><a
href="#functions-path-absolute"><code>$path.absolute()</code></a></td></tr>
            <tr><th>5.5.6</th><td><a
href="#functions-path-simple"><code>$path.simple()</code></a></td></tr>
            <tr><th>5.5.7</th><td><a
href="#functions-path-sub_path"><code>$path.sub_path()</code></a></td></tr>
            <tr><th>5.5.8</th><td><a
href="#functions-path-super_path"><code>$path.super_path()</code></a></td></tr>
            <tr><th>5.5.9</th><td><a
href="#functions-path-directory"><code>$path.directory()</code></a></td></tr>
            <tr><th>5.5.10</th><td><a
href="#functions-path-root_directory"><code>$path.root_directory()</code></a></td></tr>
            <tr><th>5.5.11</th><td><a
href="#functions-path-leaf"><code>$path.leaf()</code></a></td></tr>
            <tr><th>5.5.12</th><td><a
href="#functions-path-relative"><code>$path.relative()</code></a></td></tr>
            <tr><th>5.5.13</th><td><a
href="#functions-path-base"><code>$path.base()</code></a></td></tr>
            <tr><th>5.5.14</th><td><a
href="#functions-path-extension"><code>$path.extension()</code></a></td></tr>
            <tr><th>5.5.15</th><td><a
href="#functions-path-complete"><code>$path.complete()</code></a></td></tr>
            <tr><th>5.5.16</th><td><a
href="#functions-path-canonicalize"><code>$path.canonicalize()</code></a></td></tr>
            <tr><th>5.5.17</th><td><a
href="#functions-path-normalize"><code>$path.normalize()</code>,
<code>$path.try_normalize()</code></a></td></tr>
            <tr><th>5.5.18</th><td><a
href="#functions-path-actualize"><code>$path.actualize()</code>,
<code>$path.try_actualize()</code></a></td></tr>
            <tr><th>5.5.19</th><td><a
href="#functions-path-size"><code>$path.size()</code></a></td></tr>
            <tr><th>5.5.20</th><td><a
href="#functions-path-sort"><code>$path.sort()</code></a></td></tr>
            <tr><th>5.5.21</th><td><a
href="#functions-path-find"><code>$path.find()</code></a></td></tr>
            <tr><th>5.5.22</th><td><a
href="#functions-path-find_index"><code>$path.find_index()</code></a></td></tr>
            <tr><th>5.5.23</th><td><a
href="#functions-path-match"><code>$path.match()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.6</th><td><a href="#functions-name">Name Functions</a>
          <table class="toc">
            <tr><th>5.6.1</th><td><a
href="#functions-name-name"><code>$name.name()</code></a></td></tr>
            <tr><th>5.6.2</th><td><a
href="#functions-name-extension"><code>$name.extension()</code></a></td></tr>
            <tr><th>5.6.3</th><td><a
href="#functions-name-directory"><code>$name.directory()</code></a></td></tr>
            <tr><th>5.6.4</th><td><a
href="#functions-name-target_type"><code>$name.target_type()</code></a></td></tr>
            <tr><th>5.6.5</th><td><a
href="#functions-name-project"><code>$name.project()</code></a></td></tr>
            <tr><th>5.6.6</th><td><a
href="#functions-name-is_a"><code>$name.is_a()</code></a></td></tr>
            <tr><th>5.6.7</th><td><a
href="#functions-name-filter"><code>$name.filter()</code>,
<code>$name.filter_out()</code></a></td></tr>
            <tr><th>5.6.8</th><td><a
href="#functions-name-size"><code>$name.size()</code></a></td></tr>
            <tr><th>5.6.9</th><td><a
href="#functions-name-sort"><code>$name.sort()</code></a></td></tr>
            <tr><th>5.6.10</th><td><a
href="#functions-name-find"><code>$name.find()</code></a></td></tr>
            <tr><th>5.6.11</th><td><a
href="#functions-name-find_index"><code>$name.find_index()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.7</th><td><a href="#functions-target">Target Functions</a>
          <table class="toc">
            <tr><th>5.7.1</th><td><a
href="#functions-target-path"><code>$target.path()</code></a></td></tr>
            <tr><th>5.7.2</th><td><a
href="#functions-target-process_path"><code>$target.process_path()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.8</th><td><a href="#functions-regex">Regex Functions</a>
          <table class="toc">
            <tr><th>5.8.1</th><td><a
href="#functions-regex-match"><code>$regex.match()</code></a></td></tr>
            <tr><th>5.8.2</th><td><a
href="#functions-regex-find_match"><code>$regex.find_match()</code></a></td></tr>
            <tr><th>5.8.3</th><td><a
href="#functions-regex-filter_match"><code>$regex.filter_match()</code>,
<code>$regex.filter_out_match()</code></a></td></tr>
            <tr><th>5.8.4</th><td><a
href="#functions-regex-search"><code>$regex.search()</code></a></td></tr>
            <tr><th>5.8.5</th><td><a
href="#functions-regex-find_search"><code>$regex.find_search()</code></a></td></tr>
            <tr><th>5.8.6</th><td><a
href="#functions-regex-filter_search"><code>$regex.filter_search()</code>,
<code>$regex.filter_out_search()</code></a></td></tr>
            <tr><th>5.8.7</th><td><a
href="#functions-regex-replace"><code>$regex.replace()</code></a></td></tr>
            <tr><th>5.8.8</th><td><a
href="#functions-regex-replace_lines"><code>$regex.replace_lines()</code></a></td></tr>
            <tr><th>5.8.9</th><td><a
href="#functions-regex-split"><code>$regex.split()</code></a></td></tr>
            <tr><th>5.8.10</th><td><a
href="#functions-regex-merge"><code>$regex.merge()</code></a></td></tr>
            <tr><th>5.8.11</th><td><a
href="#functions-regex-apply"><code>$regex.apply()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.9</th><td><a href="#functions-json">JSON Functions</a>
          <table class="toc">
            <tr><th>5.9.1</th><td><a
href="#functions-json-value_type"><code>$json.value_type()</code></a></td></tr>
            <tr><th>5.9.2</th><td><a
href="#functions-json-value_size"><code>$json.value_size()</code></a></td></tr>
            <tr><th>5.9.3</th><td><a
href="#functions-json-member_name"><code>$json.member_name()</code></a></td></tr>
            <tr><th>5.9.4</th><td><a
href="#functions-json-member_value"><code>$json.member_value()</code></a></td></tr>
            <tr><th>5.9.5</th><td><a
href="#functions-json-object_names"><code>$json.object_names()</code></a></td></tr>
            <tr><th>5.9.6</th><td><a
href="#functions-json-array_size"><code>$json.array_size()</code></a></td></tr>
            <tr><th>5.9.7</th><td><a
href="#functions-json-array_find"><code>$json.array_find()</code></a></td></tr>
            <tr><th>5.9.8</th><td><a
href="#functions-json-array_find_index"><code>$json.array_find_index()</code></a></td></tr>
            <tr><th>5.9.9</th><td><a
href="#functions-json-load"><code>$json.load()</code></a></td></tr>
            <tr><th>5.9.10</th><td><a
href="#functions-json-parse"><code>$json.parse()</code></a></td></tr>
            <tr><th>5.9.11</th><td><a
href="#functions-json-serialize"><code>$json.serialize()</code></a></td></tr>
            <tr><th>5.9.12</th><td><a
href="#functions-json-size"><code>$json.size()</code></a></td></tr>
            <tr><th>5.9.13</th><td><a
href="#functions-json-keys"><code>$json.keys()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.10</th><td><a href="#functions-process">Process
Functions</a>
          <table class="toc">
            <tr><th>5.10.1</th><td><a
href="#functions-process-run"><code>$process.run()</code></a></td></tr>
            <tr><th>5.10.2</th><td><a
href="#functions-process-run_regex"><code>$process.run_regex()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.11</th><td><a href="#functions-filesystem">Filesystem
Functions</a>
          <table class="toc">
            <tr><th>5.11.1</th><td><a
href="#functions-filesystem-file_exists"><code>$filesystem.file_exists()</code></a></td></tr>
            <tr><th>5.11.2</th><td><a
href="#functions-filesystem-directory_exists"><code>$filesystem.directory_exists()</code></a></td></tr>
            <tr><th>5.11.3</th><td><a
href="#functions-filesystem-path_search"><code>$filesystem.path_search()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.12</th><td><a href="#functions-project_name">Project Name
Functions</a>
          <table class="toc">
            <tr><th>5.12.1</th><td><a
href="#functions-project_name-string"><code>$project_name.string()</code></a></td></tr>
            <tr><th>5.12.2</th><td><a
href="#functions-project_name-base"><code>$project_name.base()</code></a></td></tr>
            <tr><th>5.12.3</th><td><a
href="#functions-project_name-extension"><code>$project_name.extension()</code></a></td></tr>
            <tr><th>5.12.4</th><td><a
href="#functions-project_name-variable"><code>$project_name.variable()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.13</th><td><a href="#functions-process-path">Process Path
Functions</a>
          <table class="toc">
            <tr><th>5.13.1</th><td><a
href="#functions-process_path-recall"><code>$process_path.recall()</code></a></td></tr>
            <tr><th>5.13.2</th><td><a
href="#functions-process_path-effect"><code>$process_path.effect()</code></a></td></tr>
            <tr><th>5.13.3</th><td><a
href="#functions-process_path-name"><code>$process_path.name()</code></a></td></tr>
            <tr><th>5.13.4</th><td><a
href="#functions-process_path-checksum"><code>$process_path.checksum()</code></a></td></tr>
            <tr><th>5.13.5</th><td><a
href="#functions-process_path-env_checksum"><code>$process_path.env_checksum()</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>5.14</th><td><a href="#functions-target-triplet">Target
Triplet Functions</a>
          <table class="toc">
            <tr><th>5.14.1</th><td><a
href="#functions-target_triplet-string"><code>$target_triplet.string()</code></a></td></tr>
            <tr><th>5.14.2</th><td><a
href="#functions-target_triplet-representation"><code>$target_triplet.representation()</code></a></td></tr>
          </table>
        </td></tr>
      </table>
    </td></tr>
    <tr><th>6</th><td><a href="#directives">Directives</a>
      <table class="toc">
        <tr><th>6.1</th><td><a
href="#directives-define"><code>define</code></a></td></tr>
        <tr><th>6.2</th><td><a
href="#directives-include"><code>include</code></a></td></tr>
        <tr><th>6.3</th><td><a
href="#directives-source"><code>source</code></a></td></tr>
      </table>
    </td></tr>
    <tr><th>7</th><td><a href="#attributes">Attributes</a></td></tr>
    <tr><th>8</th><td><a href="#name-patterns">Name Patterns</a></td></tr>
    <tr><th>9</th><td><a href="#module-config"><code>config</code> Module</a>
      <table class="toc">
        <tr><th>9.1</th><td><a href="#module-config-hermetic">Hermetic Build
Configurations</a></td></tr>
      </table>
    </td></tr>
    <tr><th>10</th><td><a href="#module-test"><code>test</code>
Module</a></td></tr>
    <tr><th>11</th><td><a href="#module-install"><code>install</code>
Module</a>
      <table class="toc">
        <tr><th>11.1</th><td><a href="#install-reloc">Relocatable
Installation</a></td></tr>
        <tr><th>11.2</th><td><a href="#install-filter">Installation
Filtering</a></td></tr>
      </table>
    </td></tr>
    <tr><th>12</th><td><a href="#module-version"><code>version</code>
Module</a></td></tr>
    <tr><th>13</th><td><a href="#module-bin"><code>bin</code> Module</a>
      <table class="toc">
        <tr><th>13.1</th><td><a href="#module-bin-target-types">Binary Target
Types</a>
          <table class="toc">
            <tr><th>13.1.1</th><td><a
href="#module-bin-target-types-lib"><code>lib{}</code>, <code>liba{}</code>,
<code>libs{}</code></a></td></tr>
            <tr><th>13.1.2</th><td><a
href="#module-bin-target-types-libu"><code>libul{}</code>,
<code>libue{}</code>, <code>libua{}</code>, <code>libus{}</code></a></td></tr>
            <tr><th>13.1.3</th><td><a
href="#module-bin-target-types-obj"><code>obj{}</code>, <code>obje{}</code>,
<code>obja{}</code>, <code>objs{}</code></a></td></tr>
            <tr><th>13.1.4</th><td><a
href="#module-bin-target-types-bmi"><code>bmi{}</code>, <code>bmie{}</code>,
<code>bmia{}</code>, <code>bmis{}</code></a></td></tr>
            <tr><th>13.1.5</th><td><a
href="#module-bin-target-types-hbmi"><code>hbmi{}</code>,
<code>hbmie{}</code>, <code>hbmia{}</code>, <code>hbmis{}</code></a></td></tr>
            <tr><th>13.1.6</th><td><a
href="#module-bin-target-types-def"><code>def{}</code></a></td></tr>
          </table>
        </td></tr>
      </table>
    </td></tr>
    <tr><th>14</th><td><a href="#module-cc"><code>cc</code> Module</a>
      <table class="toc">
        <tr><th>14.1</th><td><a href="#cc-config">C-Common Configuration
Variables</a></td></tr>
        <tr><th>14.2</th><td><a href="#cc-target-types">C-Common Target
Types</a>
          <table class="toc">
            <tr><th>14.2.1</th><td><a
href="#cc-target-types-pc"><code>pc{}</code>, <code>pca{}</code>,
<code>pcs{}</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>14.3</th><td><a href="#cc-internal-scope">Compilation Internal
Scope</a></td></tr>
        <tr><th>14.4</th><td><a href="#cc-auto-symexport">Automatic DLL Symbol
Exporting</a></td></tr>
        <tr><th>14.5</th><td><a href="#cc-import-installed">Importation of
Installed Libraries</a>
          <table class="toc">
            <tr><th>14.5.1</th><td><a
href="#cc-import-installed-sysroot">Rewriting Installed Libraries System Root
(sysroot)</a></td></tr>
          </table>
        </td></tr>
        <tr><th>14.6</th><td><a href="#cc-gcc">GCC Compiler
Toolchain</a></td></tr>
        <tr><th>14.7</th><td><a href="#cc-clang">Clang Compiler Toolchain</a>
          <table class="toc">
            <tr><th>14.7.1</th><td><a href="#cc-clang-msvc">Clang Targeting
MSVC</a></td></tr>
          </table>
        </td></tr>
        <tr><th>14.8</th><td><a href="#cc-msvc">MSVC Compiler
Toolchain</a></td></tr>
      </table>
    </td></tr>
    <tr><th>15</th><td><a href="#module-c"><code>c</code> Module</a>
      <table class="toc">
        <tr><th>15.1</th><td><a href="#c-config">C Configuration
Variables</a></td></tr>
        <tr><th>15.2</th><td><a href="#c-target-types">C Target Types</a>
          <table class="toc">
            <tr><th>15.2.1</th><td><a
href="#c-target-types-c"><code>c{}</code>, <code>h{}</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>15.3</th><td><a href="#c-objc">Objective-C
Compilation</a></td></tr>
        <tr><th>15.4</th><td><a href="#c-as-cpp">Assembler with C Preprocessor
Compilation</a></td></tr>
        <tr><th>15.5</th><td><a href="#c-predefs">C Compiler Predefined Macro
Extraction</a></td></tr>
      </table>
    </td></tr>
    <tr><th>16</th><td><a href="#module-cxx"><code>cxx</code> Module</a>
      <table class="toc">
        <tr><th>16.1</th><td><a href="#cxx-config">C++ Configuration
Variables</a></td></tr>
        <tr><th>16.2</th><td><a href="#cxx-target-types">C++ Target Types</a>
          <table class="toc">
            <tr><th>16.2.1</th><td><a
href="#cxx-target-types-cxx"><code>cxx{}</code>, <code>hxx{}</code>,
<code>ixx{}</code>, <code>txx{}</code>, <code>mxx{}</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>16.3</th><td><a href="#cxx-modules">C++ Modules Support</a>
          <table class="toc">
            <tr><th>16.3.1</th><td><a href="#cxx-modules-intro">Modules
Introduction</a></td></tr>
            <tr><th>16.3.2</th><td><a href="#cxx-modules-build">Building
Modules</a></td></tr>
            <tr><th>16.3.3</th><td><a href="#cxx-modules-symexport">Module
Symbols Exporting</a></td></tr>
            <tr><th>16.3.4</th><td><a href="#cxx-modules-install">Modules
Installation</a></td></tr>
            <tr><th>16.3.5</th><td><a href="#cxx-modules-guidelines">Modules
Design Guidelines</a></td></tr>
            <tr><th>16.3.6</th><td><a
href="#cxx-modules-existing">Modularizing Existing Code</a></td></tr>
          </table>
        </td></tr>
        <tr><th>16.4</th><td><a href="#cxx-objcxx">Objective-C++
Compilation</a></td></tr>
        <tr><th>16.5</th><td><a href="#cxx-predefs">C++ Compiler Predefined
Macro Extraction</a></td></tr>
      </table>
    </td></tr>
    <tr><th>17</th><td><a href="#module-in"><code>in</code>
Module</a></td></tr>
    <tr><th>18</th><td><a href="#module-bash"><code>bash</code>
Module</a></td></tr>
    <tr><th>19</th><td><a href="#json-dump">Appendix A &#8211; JSON Dump
Format</a></td></tr>
  </table>

  </div> <!-- noprint -->
  <h1 id="preface" class="preface">Preface</h1>

  <p>This document describes the <code>build2</code> build system. For the
  build system driver command line interface refer to the <a
  href="b.xhtml"><code><b>b(1)</b></code></a> man pages. For other tools in
  the <code>build2</code> toolchain (package and project managers, etc) see
  the <a href="https://build2.org/doc.xhtml">Documentation</a> index.</p>

  <h1 id="intro">1 Introduction</h1>

  <p>The <code>build2</code> build system is a native, cross-platform build
  system with a terse, mostly declarative description language, a conceptual
  model of build, and a uniform interface with consistent behavior across
  platforms and compilers.</p>

  <p>Those familiar with <code>make</code> will see many similarities, though
  mostly conceptual rather than syntactic. This is not by accident since
  <code>build2</code> borrows the fundamental DAG-based build model from
  original <code>make</code> and many of its conceptual extensions from GNU
  <code>make</code>. We believe, paraphrasing a famous quote, that <i>those
  who do not understand <code>make</code> are condemned to reinvent it,
  poorly.</i> So our goal with <code>build2</code> was to reinvent
  <code>make</code> <i>well</i> while handling the demands and complexity of
  modern cross-platform software development.</p>

  <p>Like <code>make</code>, <code>build2</code> is an <i>"honest"</i> build
  system without magic or black boxes. You can expect to understand what's
  going on underneath and be able to customize most of its behavior to suit
  your needs. This is not to say that it's not an <i>opinionated</i> build
  system and if you find yourself "fighting" some of its fundamental design
  choices, it would probably be wiser to look for alternatives.</p>

  <p>We believe the importance and complexity of the problem warranted the
  design of a new purpose-built language and will hopefully justify the time
  it takes for you to master it. In the end we hope <code>build2</code> will
  make creating and maintaining build infrastructure for your projects a
  pleasant task.</p>

  <p>Also note that <code>build2</code> is not specific to C/C++ or even to
  compiled languages; its build model is general enough to handle any
  DAG-based operations. See the <a href="#module-bash"><code>bash</code></a>
  module for a good example.</p>

  <p>While the build system is part of a larger, well-integrated build
  toolchain that includes the package and project dependency managers, it does
  not depend on them and its standalone usage is the only subject of this
  manual.</p>

  <p>We begin with a tutorial introduction that aims to show the essential
  elements of the build system on real examples but without getting into too
  much detail. Specifically, we want to quickly get to the point where we can
  build useful executable and library projects.</p>

  <h2 id="intro-hello">1.1 Hello, World</h2>

  <p>Let's start with the customary <i>"Hello, World"</i> example: a single
  source file from which we would like to build an executable:</p>

  <pre>$ tree hello/
hello/
└── hello.cxx

$ cat hello/hello.cxx

#include &lt;iostream>

int main ()
{
  std::cout &lt;&lt; "Hello, World!" &lt;&lt; std::endl;
}</pre>

  <p>While this very basic program hardly resembles what most software
  projects look like today, it is useful for introducing key build system
  concepts without getting overwhelmed. In this spirit we will also use the
  <code>build2</code> <i>simple project</i> structure, which, similarly,
  should only be used for basic needs.</p>

  <p>To turn our <code>hello/</code> directory into a simple project all we
  need to do is add a <code>buildfile</code>:</p>

  <pre>$ tree hello/
hello/
├── hello.cxx
└── buildfile

$ cat hello/buildfile

using cxx

exe{hello}: cxx{hello.cxx}</pre>

  <p>Let's start from the bottom: the second line is a <i>dependency
  declaration</i>. On the left hand side of <code>:</code> we have a
  <i>target</i>, the <code>hello</code> executable, and on the right hand side
  &#8211; a <i>prerequisite</i>, the <code>hello.cxx</code> source file. Those
  <code>exe</code> and <code>cxx</code> in <code>exe{...}</code> and
  <code>cxx{...}</code> are called <i>target types</i>. In fact, for clarity,
  target type names are always mentioned with trailing <code>{}</code>, for
  example, "the <code>exe{}</code> target type denotes an executable".</p>

  <p>Notice that the dependency declaration does not specify <i>how</i> to
  build an executable from a C++ source file &#8211; this is the job of a
  <i>rule</i>. When the build system needs to update a target, it tries to
  <i>match</i> a suitable rule based on the types of the target and its
  prerequisites. The <code>build2</code> core has a number of predefined
  fundamental rules with the rest coming from <i>build system modules</i>. For
  example, the <code>cxx</code> module defines a number of rules for compiling
  C++ source code as well as linking executables and libraries.</p>

  <p>It should now be easy to guess what the first line of our
  <code>buildfile</code> does: it loads the <code>cxx</code> module which
  defines the rules necessary to build our program (it also registers the
  <code>cxx{}</code> target type).</p>

  <p>Let's now try to build and run our program (<code>b</code> is the build
  system driver):</p>

  <pre>$ cd hello/  # Change to project root.

$ b
c++ cxx{hello} -> obje{hello}
ld exe{hello}

$ ls -1
buildfile
hello.cxx
hello
hello.d
hello.o
hello.o.d

$ ./hello
Hello, World!</pre>

  <p>Or, if we are on Windows and using Visual Studio:</p>

  <pre>> cd hello

> b
c++ cxx{hello} -> obje{hello}
ld exe{hello}

> dir /b
buildfile
hello.cxx
hello.exe
hello.exe.d
hello.exe.obj
hello.exe.obj.d

> .\hello.exe
Hello, World!</pre>

  <p>By default <code>build2</code> uses the same C++ compiler it was built
  with and without passing any extra options, such as debug or optimization,
  target architecture, etc. To change these defaults we use <i>configuration
  variables</i>. For example, to specify a different C++ compiler we use
  <code>config.cxx</code>:</p>

  <pre>$ b config.cxx=clang++</pre>

  <div class="note">
  <p>For Visual Studio, <code>build2</code> by default will use the latest
  available version and build for the <code>x86_64</code> target
  (<code>x64</code> in the Microsoft's terminology). You can, however,
  override these defaults by either running from a suitable Visual Studio
  development command prompt or by specifying an absolute path to
  <code>cl</code> that you wish to use. For example (notice the use of inner
  quotes):</p>

  <pre>> b "config.cxx='...\VC\Tools\MSVC\14.23.28105\bin\Hostx64\x86\cl'"</pre>

  <p>See <a href="#cc-msvc">MSVC Compiler Toolchain</a> for details.</p>
  </div>

  <p>Similarly, for additional compile options, such as debug information or
  optimization level, there is <code>config.cxx.coptions</code>. For
  example:</p>

  <pre>$ b config.cxx=clang++ config.cxx.coptions=-g</pre>

  <div class="note">
  <p>These and other configuration variables will be discussed in more detail
  later. We will also learn how to make our configuration persistent so that
  we don't have to repeat such long command lines on every build system
  invocation.</p>

  <p>Similar to <code>config.cxx</code>, there is also <code>config.c</code>
  for specifying the C compiler. Note, however, that if your project uses both
  C and C++, then you normally only need to specify one of them &#8211;
  <code>build2</code> will determine the other automatically.</p>
  </div>

  <p>Let's discuss a few points about the build output. Firstly, to reduce the
  noise, the commands being executed are by default shown abbreviated and with
  the same target type notation as we used in the <code>buildfile</code>. For
  example:</p>

  <pre>c++ cxx{hello} -> obje{hello}
ld exe{hello}</pre>

  <p>If, however, you would like to see the actual command lines, you can pass
  <code>-v</code> (to see even more, there is the <code>-V</code> as well as
  <code>--verbose</code> options; see <a
  href="b.xhtml"><code><b>b(1)</b></code></a> for details). For example:</p>

  <pre>$ b -v
g++ -o hello.o -c hello.cxx
g++ -o hello hello.o</pre>

  <p>Most of the files produced by the build system should be
  self-explanatory: we have the object file (<code>hello.o</code>,
  <code>hello.obj</code>) and executable (<code>hello</code>,
  <code>hello.exe</code>). For each of them we also have the corresponding
  <code>.d</code> files which store the <i>auxiliary dependency
  information</i>, things like compile options, header dependencies, etc.</p>

  <p>To remove the build system output we use the <code>clean</code>
  <i>operation</i> (if no operation is specified, the default is
  <code>update</code>):</p>

  <pre>$ b clean
rm exe{hello}
rm obje{hello}

$ ls -1
buildfile
hello.cxx</pre>

  <p>One of the main reasons behind the <i>target type</i> concept is the
  platform/compiler-specified variances in file names as illustrated by the
  above listings. In our <code>buildfile</code> we refer to the executable
  target as <code>exe{hello}</code>, not as <code>hello.exe</code> or
  <code>hello$EXT</code>. The actual file extension, if any, will be
  determined based on the compiler's target platform by the rule doing the
  linking. In this sense, target types are a platform-independent replacement
  of file extensions (though they do have other benefits, such as allowing
  non-file targets as well as being hierarchical; see <a
  href="#targets-types">Target Types</a> for details).</p>

  <p>Let's revisit the dependency declaration line from our
  <code>buildfile</code>:</p>

  <pre>exe{hello}: cxx{hello.cxx}</pre>

  <p>In light of target types replacing file extensions this looks
  tautological: why do we need to specify both the <code>cxx{}</code> target
  type <i>and</i> the <code>.cxx</code> file extension? In fact, we don't have
  to if we specify the default file extension for the <code>cxx{}</code>
  target type. Here is our updated <code>buildfile</code> in its entirety:</p>

  <pre>using cxx

cxx{*}: extension = cxx

exe{hello}: cxx{hello}</pre>

  <p>Let's unpack the new line. What we have here is a <i>target
  type/pattern-specific variable</i>. It only applies to targets of the
  <code>cxx{}</code> type whose names match the <code>*</code> wildcard
  pattern. The <code>extension</code> variable name is reserved by the
  <code>build2</code> core for specifying target type extensions.</p>

  <p>Let's see how all these pieces fit together. When the build system needs
  to update <code>exe{hello}</code>, it searches for a suitable rule. A rule
  from the <code>cxx</code> module matches since it knows how to build a
  target of type <code>exe{}</code> from a prerequisite of type
  <code>cxx{}</code>. When the matched rule is <i>applied</i>, it searches for
  a target for the <code>cxx{hello}</code> prerequisite. During this search,
  the <code>extension</code> variable is looked up and its value is used to
  end up with the <code>hello.cxx</code> file.</p>

  <div class="note">
  <p>To resolve a rule match ambiguity or to override a default match
  <code>build2</code> uses <i>rule hints</i>. For example, if we wanted link a
  C executable using the C++ link rule:</p>

  <pre>[rule_hint=cxx] exe{hello}: c{hello}</pre>
  </div>

  <p>Here is our new dependency declaration again:</p>

  <pre>exe{hello}: cxx{hello}</pre>

  <p>It has the canonical form: no extensions, only target types. Sometimes
  explicit extension specification is still necessary, for example, if your
  project uses multiple extensions for the same file type. But if unnecessary,
  it should be omitted for brevity.</p>

  <div class="note">
  <p>If you prefer the <code>.cpp</code> file extension and your source file
  is called <code>hello.cpp</code>, then the only line in our
  <code>buildfile</code> that needs changing is the <code>extension</code>
  variable assignment:</p>

  <pre>cxx{*}: extension = cpp</pre>
  </div>

  <p>Let's say our <code>hello</code> program got complicated enough to
  warrant moving some functionality into a separate source/header module (or a
  real C++ module). For example:</p>

  <pre>$ tree hello/
hello/
├── hello.cxx
├── utility.hxx
├── utility.cxx
└── buildfile</pre>

  <p>This is what our updated <code>buildfile</code> could look like:</p>

  <pre>using cxx

hxx{*}: extension = hxx
cxx{*}: extension = cxx

exe{hello}: cxx{hello} hxx{utility} cxx{utility}</pre>

  <p>Nothing really new here: we've specified the default extension for the
  <code>hxx{}</code> target type and listed the new header and source files as
  prerequisites. If you have experience with other build systems, then
  explicitly listing headers might seem strange to you. As will be discussed
  later, in <code>build2</code> we have to explicitly list all the
  prerequisites of a target that should end up in a source distribution of our
  project.</p>

  <div class="note">
  <p>You don't have to list <i>all</i> headers that you include, only the ones
  belonging to your project. Like all modern C/C++ build systems,
  <code>build2</code> performs automatic header dependency extraction.</p>
  </div>

  <p>In real projects with a substantial number of source files, repeating
  target types and names will quickly become noisy. To tidy things up we can
  use <i>name generation</i>. Here are a few examples of dependency
  declarations equivalent to the above:</p>

  <pre>exe{hello}: cxx{hello utility} hxx{utility}
exe{hello}: cxx{hello} {hxx cxx}{utility}</pre>

  <p>The last form is probably the best choice if your project contains a
  large number of header/source pairs. Here is a more realistic example:</p>

  <pre>exe{hello}: {    cxx}{hello}               \
            {hxx    }{forward types}       \
            {hxx cxx}{format print utility}</pre>

  <p>Manually listing a prerequisite every time we add a new source file to
  our project is both tedious and error prone. Instead, we can automate our
  dependency declarations with <i>wildcard name patterns</i>. For example:</p>

  <pre>exe{hello}: {hxx cxx}{*}</pre>

  <p>Based on the previous discussion of default extensions, you can probably
  guess how this works: for each target type the value of the
  <code>extension</code> variable is added to the pattern and files matching
  the result become prerequisites. So, in our case, we will end up with files
  matching the <code>*.hxx</code> and <code>*.cxx</code> wildcard
  patterns.</p>

  <p>In more complex projects it is often convenient to organize source code
  into subdirectories. To handle such projects we can use the recursive
  wildcard:</p>

  <pre>exe{hello}: {hxx cxx}{**}</pre>

  <div class="note">
  <p>Using wildcards is somewhat controversial. Patterns definitely make
  development more pleasant and less error prone: you don't need to update
  your <code>buildfile</code> every time you add, remove, or rename a source
  file and you won't forget to explicitly list headers, a mistake that is
  often only detected when trying to build a source distribution of a project.
  On the other hand, there is the possibility of including stray source files
  into your build without noticing. And, for more complex projects, name
  patterns can become fairly complex (see <a href="#name-patterns">Name
  Patterns</a> for details). Note also that on modern hardware the performance
  of wildcard searches hardly warrants a consideration.</p>

  <p>In our experience, when combined with modern version control systems like
  <code>git(1)</code>, stray source files are rarely an issue and generally
  the benefits of wildcards outweigh their drawbacks. But, in the end, whether
  to use them or not is a personal choice and, as shown above,
  <code>build2</code> supports both approaches.</p>
  </div>

  <p>And that's about all there is to our <code>hello</code> example. To
  summarize, we've seen that to build a simple project we need a single
  <code>buildfile</code> which itself doesn't contain much more than a
  dependency declaration for what we want to build. But we've also mentioned
  that simple projects are only really meant for basics. So let's convert our
  <code>hello</code> example to the <i>standard project</i> structure which is
  what we will be using for most of our real development.</p>

  <div class="note">
  <p>Simple projects have so many restrictions and limitations that they are
  hardly usable for anything but, well, <i>really</i> simple projects.</p>

  <p>Specifically, such projects cannot be imported by other projects nor can
  they use build system modules that require bootstrapping. Notably, this
  includes the <code>dist</code> and <code>config</code> modules (the
  <code>test</code> and <code>install</code> modules are loaded implicitly).
  And without the <code>config</code> module there is no support for
  persistent configurations.</p>

  <p>As a result, you should only use a simple project if you are happy to
  always build in the source directory and with the default build
  configuration or willing to specify the output directory and/or custom
  configuration on every invocation. In other words, expect an experience
  similar to a plain <code>Makefile</code>.</p>

  <p>One notable example where simple projects are handy is a <i>glue
  <code>buildfile</code></i> that "pulls" together several other projects,
  usually for convenience of development. See <a href="#intro-import">Target
  Importation</a> for details.</p>
  </div>

  <h2 id="intro-proj-struct">1.2 Project Structure</h2>

  <p>A <code>build2</code> <i>standard project</i> has the following overall
  layout:</p>

  <pre>hello/
├── build/
│   ├── bootstrap.build
│   └── root.build
├── ...
└── buildfile</pre>

  <p>Specifically, the project's root directory should contain the
  <code>build/</code> subdirectory as well as the root <code>buildfile</code>.
  The <code>build/</code> subdirectory contains project-wide build system
  information.</p>

  <div class="note">
  <p>The <a
  href="../../bdep/doc/bdep-new.xhtml"><code><b>bdep-new(1)</b></code></a>
  command is an easy way to create the standard layout executable
  (<code>-t&#160;exe</code>) and library (<code>-t&#160;lib</code>) projects.
  To change the C++ file extensions to <code>.hpp/.cpp</code>, pass <code>-l
  c++,cpp</code>. For example:</p>

  <pre>$ bdep new --no-init -l c++,cpp -t exe hello</pre>
  </div>

  <div class="note">
  <p>It is also possible to use an alternative build file/directory naming
  scheme where every instance of the word <i>build</i> is replaced with
  <i>build2</i>, for example:</p>

  <pre>hello/
├── build2/
│   ├── bootstrap.build2
│   └── root.build2
├── ...
└── build2file</pre>

  <p>Note that the naming must be consistent within a project with all the
  filesystem entries either following <i>build</i> or <i>build2</i> scheme. In
  other words, we cannot call the directory <code>build2/</code> while still
  using <code>buildfile</code>.</p>

  <p>The alternative naming scheme is primarily useful when adding
  <code>build2</code> support to an existing project along with other build
  systems. In this case, the fairly generic standard names might already be in
  use. For example, it is customary to have <code>build/</code> in
  <code>.gitignore</code>. Plus more specific naming will make it easier to
  identify files and directories as belonging to the <code>build2</code>
  support. For new projects as well as for existing projects that are
  switching exclusively to <code>build2</code> the standard naming scheme is
  recommended.</p>

  <p>To create a project with the alternative naming using <a
  href="../../bdep/doc/bdep-new.xhtml"><code><b>bdep-new(1)</b></code></a>
  pass the <code>alt-naming</code> project type sub-option. For example:</p>

  <pre>$ bdep new -t exe,alt-naming ...</pre>
  </div>

  <p>To support lazy loading of subprojects (discussed later), reading of the
  project's build information is split into two phases: bootstrapping and
  loading. During bootstrapping the project's
  <code>build/bootstrap.build</code> file is read. Then, when (and if) the
  project is loaded completely, its <code>build/root.build</code> file is read
  followed by the <code>buildfile</code> (normally from the project root but
  possibly from a subdirectory).</p>

  <p>The <code>bootstrap.build</code> file is required. Let's see what it
  would look like for a typical project using our <code>hello</code> as an
  example:</p>

  <pre>project = hello

using version
using config
using test
using install
using dist</pre>

  <p>The first non-comment line in <code>bootstrap.build</code> should be the
  assignment of the project name to the <code>project</code> variable. After
  that, a typical <code>bootstrap.build</code> file loads a number of build
  system modules. While most modules can be loaded during the project load
  phase in <code>root.build</code>, certain modules have to be loaded early,
  while bootstrapping (for example, because they define new operations).</p>

  <p>Let's examine briefly the modules loaded by our
  <code>bootstrap.build</code>: The <a
  href="#module-version"><code>version</code></a> module helps with managing
  our project versioning. With this module we only maintain the version in a
  single place (the project's <code>manifest</code> file) and it is
  automatically made available in various convenient forms throughout our
  project (<code>buildfiles</code>, header files, etc). The
  <code>version</code> module also automates versioning of snapshots between
  releases.</p>

  <p>The <code>manifest</code> file is what makes our build system project a
  <i>package</i>. It contains all the metadata that a user of a package might
  need to know: name, version, dependencies, etc., all in one place. However,
  even if you don't plan to package your project, it is a good idea to create
  a basic <code>manifest</code> if only to take advantage of the version
  management offered by the <code>version</code> module. So let's go ahead and
  add it next to our root <code>buildfile</code>:</p>

  <pre>$ tree hello/
hello/
├── build/
│   └── ...
├── ...
├── buildfile
└── manifest

$ cat hello/manifest
: 1
name: hello
version: 0.1.0
summary: hello C++ executable</pre>

  <p>The <code>config</code> module provides support for persistent
  configurations. While build configuration is a large topic that we will be
  discussing in more detail later, in a nutshell <code>build2</code> support
  for configuration is an integral part of the build system with the same
  mechanisms available to the build system core, modules, and your projects.
  However, without <code>config</code>, the configuration information is
  <i>transient</i>. That is, whatever configuration information was
  automatically discovered or that you have supplied on the command line is
  discarded after each build system invocation. With the <code>config</code>
  module, however, we can <i>configure</i> a project to make the configuration
  <i>persistent</i>. We will see an example of this shortly.</p>

  <p>Next up are the <code>test</code>, <code>install</code>, and
  <code>dist</code> modules. As their names suggest, they provide support for
  testing, installation and preparation of source distributions. Specifically,
  the <code>test</code> module defines the <code>test</code> operation, the
  <code>install</code> module defines the <code>install</code> and
  <code>uninstall</code> operations, and the <code>dist</code> module defines
  the <code>dist</code> (meta-)operation. Again, we will try them out in a
  moment.</p>

  <p>Moving on, the <code>root.build</code> file is optional though most
  projects will have it. This is the place where we define project's
  configuration variables (subject of <a href="#proj-config">Project
  Configuration</a>), establish project-wide settings, as well as load build
  system modules that provide support for the languages/tools that we use.
  Here is what it could look like for our <code>hello</code> example:</p>

  <pre>cxx.std = latest

using cxx

hxx{*}: extension = hxx
cxx{*}: extension = cxx</pre>

  <p>As you can see, we've moved the loading of the <code>cxx</code> modules
  and setting of the default file extensions from the root
  <code>buildfile</code> in our simple project to <code>root.build</code> when
  using the standard layout. We've also set the <code>cxx.std</code> variable
  to tell the <code>cxx</code> module to select the latest C++ standard
  available in any particular C++ compiler this project might be built
  with.</p>

  <div class="note">
  <p>Selecting the C++ standard for our project is a messy issue. If we don't
  specify the standard explicitly with <code>cxx.std</code>, then the default
  standard in each compiler will be used, which, currently, can range from
  C++98 to C++14. So unless you carefully write your code to work with any
  standard, this is probably not a good idea.</p>

  <p>Fixing the standard (for example, to <code>c++11</code>,
  <code>c++14</code>, etc) should work theoretically. In practice, however,
  compilers add support for new standards incrementally and many versions,
  while perfectly usable, are not feature-complete. As a result, a better
  practical strategy is to specify the set of minimum supported compiler
  versions rather than the C++ standard.</p>

  <p>There is also the issue of using libraries that require a newer standard
  in old code. For example, headers from a library that relies on C++14
  features will not compile when included in a project that is built as C++11.
   And, even if the headers compile (that is, C++14 features are only used in
  the implementation), strictly speaking, there is no guarantee that codebases
  compiled with different C++ standards are ABI compatible (in fact, some
  changes to the C++ language leave the implementations no choice but to break
  the ABI).</p>

  <p>As result, our recommendation is to set the standard to
  <code>latest</code> and specify the minimum supported compilers and versions
  in your project's documentation (see package manifest <a
  href="../../bpkg/doc/build2-package-manager-manual.xhtml#manifest-package-requires"><code>requires</code></a>
  value for one possible place). Practically, this should allow you to include
  and link any library, regardless of the C++ standard that it uses.</p>
  </div>

  <p>Let's now take a look at the root <code>buildfile</code>:</p>

  <pre>./: {*/ -build/}</pre>

  <p>In plain English, this <code>buildfile</code> declares that building this
  directory (and, since it's the root of our project, building this entire
  project) means building all its subdirectories excluding
  <code>build/</code>. Let's now try to understand how this is actually
  achieved.</p>

  <p>We already know this is a dependency declaration, <code>./</code> is the
  target, and what's after <code>:</code> are its prerequisites, which seem to
  be generated with some kind of a name pattern (the wildcard character in
  <code>*/</code> should be the giveaway). What's unusual about this
  declaration, however, is the lack of any target types plus that
  strange-looking <code>./</code>.</p>

  <p>Let's start with the missing target types. In fact, the above
  <code>buildfile</code> can be rewritten as:</p>

  <pre>dir{.}: dir{* -build}</pre>

  <p>So the trailing slash (always forward, even on Windows) is a special
  shorthand notation for <code>dir{}</code>. As we will see shortly, it fits
  naturally with other uses of directories in <code>buildfiles</code> (for
  example, in scopes).</p>

  <p>The <code>dir{}</code> target type is an <i>alias</i> (and, in fact, is
  derived from more general <code>alias{}</code>; see <a
  href="#targets-types">Target Types</a> for details). Building it means
  building all its prerequisites.</p>

  <div class="note">
  <p>If you are familiar with <code>make</code>, then you can probably see the
  similarity with the ubiquitous <code>all</code> pseudo-target. In
  <code>build2</code> we instead use directory names as more natural aliases
  for the "build everything in this directory" semantics.</p>

  <p>Note also that <code>dir{}</code> is purely an alias and doesn't have
  anything to do with the filesystem. In particular, it does not create any
  directories. If you do want explicit directory creation (which should be
  rarely needed), use the <code>fsdir{}</code> target type instead.</p>
  </div>

  <p>The <code>./</code> target is a special <i>default target</i>. If we run
  the build system without specifying the target explicitly, then this target
  is built by default. Every <code>buildfile</code> has the <code>./</code>
  target. If we don't declare it explicitly, then its declaration is implied
  with the first target in the <code>buildfile</code> as its prerequisite.
  Recall our <code>buildfile</code> from the simple <code>hello</code>
  project:</p>

  <pre>exe{hello}: cxx{hello}</pre>

  <p>It is equivalent to:</p>

  <pre>./: exe{hello}
exe{hello}: cxx{hello}</pre>

  <p>If, however, we had several targets in the same directory that we wanted
  built by default, then we would need to explicitly list them as
  prerequisites of the default target. For example:</p>

  <pre>./: exe{hello}
exe{hello}: cxx{hello}

./: exe{goodby}
exe{goodby}: cxx{goodby}</pre>

  <p>While straightforward, this is somewhat inelegant in its repetitiveness.
  To tidy things up we can use <i>dependency declaration chains</i> that allow
  us to chain together several target-prerequisite declarations in a single
  line. For example:</p>

  <pre>./: exe{hello}: cxx{hello}

./: exe{goodby}: cxx{goodby}</pre>

  <p>With dependency chains a prerequisite of the preceding target becomes a
  target itself for the following prerequisites.</p>

  <p>Let's get back to our root <code>buildfile</code>:</p>

  <pre>./: {*/ -build/}</pre>

  <p>The last unexplained bit is the <code>{*/&#160;-build/}</code> name
  pattern. All it does is exclude <code>build/</code> from the subdirectories
  to build. See <a href="#name-patterns">Name Patterns</a> for details.</p>

  <p>Let's take a look at a slightly more realistic root
  <code>buildfile</code>:</p>

  <pre>./: {*/ -build/} doc{README.md LICENSE} manifest</pre>

  <p>Here we have the customary <code>README.md</code> and
  <code>LICENSE</code> files as well as the package <code>manifest</code>.
  Listing them as prerequisites achieves two things: they will be installed
  if/when our project is installed and, as mentioned earlier, they will be
  included into the project source distribution.</p>

  <p>The <code>README.md</code> and <code>LICENSE</code> files use the
  <code>doc{}</code> target type. We could have used the generic
  <code>file{}</code> but using the more precise <code>doc{}</code> makes sure
  that they are installed into the appropriate documentation directory. The
  <code>manifest</code> file doesn't need an explicit target type since it has
  a fixed name (<code>manifest{manifest}</code> is valid but redundant).</p>

  <p>Standard project infrastructure in place, where should we put our source
  code? While we could have everything in the root directory of our project,
  just like we did with the simple layout, it is recommended to instead place
  the source code into a subdirectory named the same as the project. For
  example:</p>

  <pre>hello/
├── build/
│   └── ...
├── hello/
│   ├── hello.cxx
│   └── buildfile
├── buildfile
├── manifest
└── README.md</pre>

  <div class="note">
  <p>There are several reasons for this layout: It implements the canonical
  inclusion scheme where each header is prefixed with its project name. It
  also has a predictable name where users can expect to find our project's
  source code. Finally, this layout prevents clutter in the project's root
  directory which usually contains various other files. See <a
  href="../../build2-toolchain/doc/build2-toolchain-intro.xhtml#proj-struct">Canonical
  Project Structure</a> for details.</p>

  <p>Note, however, that this layout is not mandatory and <code>build2</code>
  is flexible enough to support various arrangements used in today's C and C++
  projects. Furthermore, the <a
  href="../../bdep/doc/bdep-new.xhtml"><code><b>bdep-new(1)</b></code></a>
  command provides a number of customization options and chances are you will
  be able to create your preferred layout automatically. See <a
  href="../../bdep/doc/bdep-new.xhtml#src-layout">SOURCE LAYOUT</a> for more
  information and examples.</p>

  <p>Note also that while we can name our header and source files however we
  like (but, again, see <a
  href="../../build2-toolchain/doc/build2-toolchain-intro.xhtml#proj-struct">Canonical
  Project Structure</a> for some sensible guidelines), C++ module interface
  files need to embed a sufficient amount of the module name suffix in their
  names to unambiguously resolve all the modules within a project. See <a
  href="#cxx-modules-build">Building Modules</a> for details.</p>
  </div>

  <p>The source subdirectory <code>buildfile</code> is identical to that of
  the simple project minus the parts moved to <code>root.build</code>:</p>

  <pre>exe{hello}: {hxx cxx}{**}</pre>

  <p>Let's now build our project and see where the build system output ends up
  in this new layout:</p>

  <pre>$ cd hello/  # Change to project root.
$ b
c++ hello/cxx{hello} -> hello/obje{hello}
ld hello/exe{hello}

$ tree ./
./
├── build/
│   └── ...
├── hello/
│   ├── hello.cxx
│   ├── hello
│   ├── hello.d
│   ├── hello.o
│   ├── hello.o.d
│   └── buildfile
├── buildfile
└── manifest

$ hello/hello
Hello, World!</pre>

  <p>If we don't specify a target to build (as in the example above), then
  <code>build2</code> will build the current directory or, more precisely, the
  default target in the <code>buildfile</code> in the current directory. We
  can also build a directory other than the current, for example:</p>

  <pre>$ b hello/</pre>

  <div class="note">
  <p>Note that the trailing slash is required. In fact, <code>hello/</code> in
  the above command line is a target and is equivalent to
  <code>dir{hello}</code>, just like in the <code>buildfiles</code>.</p>
  </div>

  <p>Or we can build a specific target:</p>

  <pre>$ b hello/exe{hello}</pre>

  <p>Naturally, nothing prevents us from building multiple targets or even
  projects in the same build system invocation. For example, if we had the
  <code>libhello</code> project next to our <code>hello/</code>, then we could
  build both at once:</p>

  <pre>$ ls -1
hello/
libhello/

$ b hello/ libhello/</pre>

  <p>Speaking of libraries, let's see what the standard project structure
  looks like for one, using <code>libhello</code> created by <a
  href="../../bdep/doc/bdep-new.xhtml"><code><b>bdep-new(1)</b></code></a> as
  an example:</p>

  <pre>$ bdep new --no-init -l c++ -t lib libhello

$ tree libhello/
libhello/
├── build/
│   ├── bootstrap.build
│   ├── root.build
│   └── export.build
├── libhello/
│   ├── hello.hxx
│   ├── hello.cxx
│   ├── export.hxx
│   ├── version.hxx.in
│   └── buildfile
├── tests/
│   └──  ...
├── buildfile
├── manifest
└── README.md</pre>

  <p>The overall layout (<code>build/</code>, <code>libhello/</code> source
  subdirectory) as well as the contents of the root files
  (<code>bootstrap.build</code>, <code>root.build</code>, root
  <code>buildfile</code>) are exactly the same. There is, however, the new
  file <code>export.build</code> in <code>build/</code>, the new subdirectory
  <code>tests/</code>, and the contents of the project's source subdirectory
  <code>libhello/</code> look quite a bit different. We will examine all of
  these differences in the coming sections, as we learn more about the build
  system.</p>

  <div class="note">
  <p>Again, this layout is not mandatory and <a
  href="../../bdep/doc/bdep-new.xhtml"><code><b>bdep-new(1)</b></code></a> can
  create a number of alternative library structures. For example, if you
  prefer the <code>include/src</code> split, try:</p>

  <pre>$ bdep new --no-init -l c++ -t lib,split libhello</pre>

  <p>See <a href="../../bdep/doc/bdep-new.xhtml#src-layout">SOURCE LAYOUT</a>
  for more examples.</p>
  </div>

  <div class="note">
  <p>The standard project structure is not type (executable, library, etc) or
  even language specific. In fact, the same project can contain multiple
  executables and/or libraries (for example, both <code>hello</code> and
  <code>libhello</code>). However, if you plan to package your projects, it is
  a good idea to keep them as separate build system projects (they can still
  reside in the same version control repository, though).</p>

  <p>Speaking of projects, this term is unfortunately overloaded to mean two
  different things at different levels of software organization. At the bottom
  we have <i>build system projects</i> which, if packaged, become
  <i>packages</i>. And at the top, related packages are often grouped into
  what is also commonly referred to as <i>projects</i>. At this point both
  usages are probably too well established to look for alternatives.</p>
  </div>

  <p>And this completes the conversion of our simple <code>hello</code>
  project to the standard structure. Earlier, when examining
  <code>bootstrap.build</code>, we mentioned that modules loaded in this file
  usually provide additional operations. So we still need to discuss what
  exactly the term <i>build system operation</i> means and see how to use
  operations that are provided by the modules we have loaded. But before we do
  that, let's see how we can build our projects <i>out of source</i> tree and
  learn about another cornerstone <code>build2</code> concept:
  <i>scopes</i>.</p>

  <h2 id="intro-dirs-scopes">1.3 Output Directories and Scopes</h2>

  <p>Two common requirements placed on modern build systems are the ability to
  build projects out of the source directory tree (referred to as just <i>out
  of source</i> vs <i>in source</i>) as well as isolation of
  <code>buildfiles</code> from each other when it comes to target and variable
  names. In <code>build2</code> these mechanisms are closely-related, integral
  parts of the build system.</p>

  <div class="note">
  <p>This tight integration has advantages, like being always available and
  working well with other build system mechanisms, as well as disadvantages,
  like the inability to implement a completely different out of source
  arrangement and/or isolation model. In the end, if you find yourself
  "fighting" this aspect of <code>build2</code>, it will likely be easier to
  use a different build system than subvert it.</p>
  </div>

  <p>Let's start with an example of an out of source build for our
  <code>hello</code> project. To recap, this is what we have:</p>

  <pre>$ ls -1
hello/

$ tree hello/
hello/
├── build/
│   └── ...
├── hello/
│   └── ...
├── buildfile
└── manifest</pre>

  <p>To start, let's build it in the <code>hello-out/</code> directory next to
  the project:</p>

  <pre>$ b hello/@hello-out/
mkdir fsdir{hello-out/}
mkdir hello-out/fsdir{hello/}
c++ hello/hello/cxx{hello} -> hello-out/hello/obje{hello}
ld hello-out/hello/exe{hello}

$ ls -1
hello/
hello-out/

$ tree hello-out/
hello-out/
└── hello/
    ├── hello
    ├── hello.d
    ├── hello.o
    └── hello.o.d</pre>

  <p>This definitely requires some explaining. Let's start from the bottom,
  with the <code>hello-out/</code> layout. It is <i>parallel</i> to the source
  directory. This mirrored side-by-side listing (of the relevant parts) should
  illustrate this clearly:</p>

  <pre>hello/             ~~>  hello-out/
└── hello/         ~~>  └── hello/
    └── hello.cxx  ~~>      └── hello.o</pre>

  <p>In fact, if we copy the contents of <code>hello-out/</code> over to
  <code>hello/</code>, we will end up with exactly the same result as in the
  in source build. And this is not accidental: an in source build is just a
  special case of an out of source build where the <i>out</i> directory is the
  same as <i>src</i>.</p>

  <div class="note">
  <p>In <code>build2</code> this parallel structure of the out and src
  directories is a cornerstone design decision and is non-negotiable, so to
  speak. In particular, out cannot be inside src. And while we can stash the
  build system output (object files, executables, etc) into (potentially
  different) subdirectories, this is not recommended. As will be shown later,
  <code>build2</code> offers better mechanisms to achieve the same benefits
  (like reduced clutter, ability to run executables) but without the drawbacks
  (like name clashes).</p>
  </div>

  <p>Let's now examine how we invoked the build system to achieve this out of
  source build. Specifically, if we were building in source, our command line
  would have been:</p>

  <pre>$ b hello/</pre>

  <p>but for the out of source build, we have:</p>

  <pre>$ b hello/@hello-out/</pre>

  <p>In fact, that strange-looking construct, <code>hello/@hello-out/</code>
  is just a more elaborate target specification that explicitly spells out the
  target's src and out directories. Let's add an explicit target type to make
  it clearer:</p>

  <pre>$ b hello/@hello-out/dir{.}</pre>

  <p>What we have on the right of <code>@</code> is the target in the out
  directory and on the left &#8211; its src directory. In plain English, this
  command line says "build me the default target from <code>hello/</code> in
  the <code>hello-out/</code> directory".</p>

  <p>As an example, if instead we wanted to build only the <code>hello</code>
  executable out of source, then the invocation would have looked like
  this:</p>

  <pre>$ b hello/hello/@hello-out/hello/exe{hello}</pre>

  <p>We could have also specified out for an in source build, but that's
  redundant:</p>

  <pre>$ b hello/@hello/</pre>

  <p>There is another example of this elaborate target specification that can
  be seen in the build diagnostics, for instance, when installing headers of a
  library (the <code>install</code> operation is discussed in the next
  section):</p>

  <pre>$ b install: libhello/@libhello-out/
...
install libhello/libhello/hxx{hello}@libhello-out/libhello/ ->
        /usr/local/include/</pre>

  <p>Notice, however, that now the target (<code>hxx{hello}</code>) is on the
  left of <code>@</code>, that is, in the src directory. It does, however,
  make sense if you think about it: our <code>hello.hxx</code> is a <i>source
  file</i>, in a sense that it is not built and it resides in the project's
  source directory. This is in contrast, for example, to the
  <code>exe{hello}</code> target which is the output of the build system and
  goes to the out directory. So in <code>build2</code> targets can be either
  in src or in out (there can also be <i>out of any project</i> targets, for
  example, installed files).</p>

  <p>The elaborate target specification can also be used in
  <code>buildfiles</code>. We haven't encountered any so far because targets
  mentioned without explicit src/out default to out and, naturally, most of
  the targets we mention in <code>buildfiles</code> are things we want built.
  One situation where you may encounter an src target mentioned explicitly is
  when specifying its installability (discussed in the next section). For
  example, if our project includes the customary <code>INSTALL</code> file, it
  probably doesn't make sense to install it. However, since it is a source
  file, we have to use the elaborate target specification when disabling its
  installation:</p>

  <pre>doc{INSTALL}@./: install = false</pre>

  <p>Note also that only targets and not prerequisites have this notion of
  src/out directories. In a sense, prerequisites are relative to the target
  they are prerequisites of and are resolved to targets in a manner that is
  specific to their target types. For <code>file{}</code>-based prerequisites
  the corresponding target in out is first looked up and, if found, used.
  Otherwise, an existing file in src is searched for and, if found, the
  corresponding target (now in src) is used. In particular, this semantics
  gives preference to generated code over static.</p>

  <div class="note">
  <p>More precisely, a prerequisite is relative to the scope (discussed below)
  in which the dependency is declared and not to the target that it is a
  prerequisite of. However, in most practical cases, this means the same
  thing.</p>
  </div>

  <p>And this pretty much covers out of source builds. Let's summarize the key
  points we have established so far: Every build has two parallel directory
  trees, src and out, with the in source build being just a special case where
  they are the same. Targets in a project can be either in the src or out
  directory though most of the time targets we mention in our
  <code>buildfiles</code> will be in out, which is the default. Prerequisites
  are relative to targets they are prerequisites of and
  <code>file{}</code>-based prerequisites are first searched for as declared
  targets in out and then as existing files in src.</p>

  <p>Note also that we can have as many out of source builds as we want and we
  can place them anywhere we want (but not inside src), say, on a RAM-backed
  disk/filesystem. As an example, let's build our <code>hello</code> project
  with two different compilers:</p>

  <pre>$ b hello/@hello-gcc/    config.cxx=g++
$ b hello/@hello-clang/  config.cxx=clang++</pre>

  <p>In the next section we will see how to permanently configure our out of
  source builds so that we don't have to keep repeating these long command
  lines.</p>

  <div class="note">
  <p>While technically you can have both in source and out of source builds at
  the same time, this is not recommended. While it may work for basic
  projects, as soon as you start using generated source code (which is fairly
  common in <code>build2</code>), it becomes difficult to predict where the
  compiler will pick generated headers. There is support for remapping
  mis-picked headers but this may not always work with older C/C++ compilers.
  Plus, as we will see in the next section, <code>build2</code> supports
  <i>forwarded configurations</i> which provide most of the benefits of an in
  source build but without the drawbacks.</p>
  </div>

  <p>Let's now turn to <code>buildfile</code> isolation. It is a common,
  well-established practice to organize complex software projects in directory
  hierarchies. One of the benefits of this organization is isolation: we can
  use the same, short file names in different subdirectories. In
  <code>build2</code> the project's directory tree is used as a basis for its
  <i>scope</i> hierarchy. In a sense, scopes are like C++ namespaces that
  automatically track the project's filesystem structure and use directories
  as their names. The following listing illustrates the parallel directory and
  scope hierarchies for our <code>hello</code> project. <span class="note">The
  <code>build/</code> subdirectory is special and does not have a
  corresponding scope.</span></p>

  <pre>hello/                   hello/
│                        {
└── hello/                 hello/
    │                      {
    └── ...                  ...
                           }
                         }</pre>

  <p>Every <code>buildfile</code> is loaded in its corresponding scope,
  variables set in a <code>buildfile</code> are set in this scope and relative
  targets mentioned in a <code>buildfile</code> are relative to this scope's
  directory. Let's "load" the <code>buildfile</code> contents from our
  <code>hello</code> project to the above listing:</p>

  <pre>hello/                   hello/
│                        {
├── buildfile              ./: {*/ -build/}
│
└── hello/                 hello/
    │                      {
    └── buildfile            exe{hello}: {hxx cxx}{**}
                           }
                         }</pre>

  <p>In fact, to be absolutely precise, we should also add the contents of
  <code>bootstrap.build</code> and <code>root.build</code> to the project's
  root scope (module loading is omitted for brevity):</p>

  <pre>hello/                   hello/
│                        {
├── build/
│   ├── bootstrap.build    project = hello
│   │
│   └── root.build         cxx.std = latest
│                          hxx{*}: extension = hxx
│                          cxx{*}: extension = cxx
│
├── buildfile              ./: {*/ -build/}
│
└── hello/                 hello/
    │                      {
    └── buildfile            exe{hello}: {hxx cxx}{**}
                           }
                         }</pre>

  <p>The above scope structure is very similar to what you will see (besides a
  lot of other things) if you build with <code>--dump&#160;match</code>. With
  this option the build system driver dumps the build state after matching
  rules to targets (see <a href="#intro-diag-debug">Diagnostics and
  Debugging</a> for more information). Here is an abbreviated output of
  building our <code>hello</code> with <code>--dump</code> (assuming an in
  source build in <code>/tmp/hello</code>):</p>

  <pre>$ b --dump match

/
{
  [target_triplet] build.host = x86_64-linux-gnu
  [string] build.host.class = linux
  [string] build.host.cpu = x86_64
  [string] build.host.system = linux-gnu

  /tmp/hello/
  {

    [dir_path] src_root = /tmp/hello/
    [dir_path] out_root = /tmp/hello/

    [dir_path] src_base = /tmp/hello/
    [dir_path] out_base = /tmp/hello/

    [project_name] project = hello
    [string] project.summary = hello executable
    [string] project.url = https://example.org/hello

    [string] version = 1.2.3
    [uint64] version.major = 1
    [uint64] version.minor = 2
    [uint64] version.patch = 3

    [string] cxx.std = latest

    [string] cxx.id = gcc
    [string] cxx.version = 8.1.0
    [uint64] cxx.version.major = 8
    [uint64] cxx.version.minor = 1
    [uint64] cxx.version.patch = 0

    [target_triplet] cxx.target = x86_64-w64-mingw32
    [string] cxx.target.class = windows
    [string] cxx.target.cpu = x86_64
    [string] cxx.target.system = mingw32

    hxx{*}: [string] extension = hxx
    cxx{*}: [string] extension = cxx

    hello/
    {
      [dir_path] src_base = /tmp/hello/hello/
      [dir_path] out_base = /tmp/hello/hello/

      dir{./}: exe{hello}
      exe{hello.}: cxx{hello.cxx}
    }

    dir{./}: dir{hello/} manifest{manifest}
  }
}</pre>

  <p>This is probably quite a bit more information than what you've expected
  to see so let's explain a couple of things. Firstly, it appears there is
  another scope outer to our project's root. In fact, <code>build2</code>
  extends scoping outside of projects with the root of the filesystem (denoted
  by the special <code>/</code>) being the <i>global scope</i>. This extension
  becomes useful when we try to build multiple unrelated projects or import
  one project into another. In this model all projects are part of a single
  scope hierarchy with the global scope at its root.</p>

  <p>The global scope is read-only and contains a number of pre-defined
  <i>build-wide</i> variables such as the build system version, host platform
  (shown in the above listing), etc.</p>

  <p>Next, inside the global scope, we see our project's root scope
  (<code>/tmp/hello/</code>). Besides the variables that we have set ourselves
  (like <code>project</code>), it also contains a number of variables set by
  the build system core (for example, <code>out_base</code>,
  <code>src_root</code>, etc) as well by build system modules (for example,
  <code>project.*</code> and <code>version.*</code> variables set by the
  <code>version</code> module and <code>cxx.*</code> variables set by the
  <code>cxx</code> module).</p>

  <p>The scope for our project's source directory (<code>hello/</code>) should
  look familiar. We again have a few special variables (<code>out_base</code>,
  <code>src_base</code>). Notice also that the name patterns in prerequisites
  have been expanded to the actual files.</p>

  <p>As you can probably guess from their names, the <code>src_*</code> and
  <code>out_*</code> variables track the association between scopes and
  src/out directories. They are maintained automatically by the build system
  core with the <code>src/out_base</code> pair set on each scope within the
  project and an additional <code>src/out_root</code> pair set on the
  project's root scope so that we can get the project's root directories from
  anywhere in the project. Note that directory paths in these variables are
  always absolute and normalized.</p>

  <p>In the above example the corresponding src/out variable pairs have the
  same values because we were building in source. As an example, this is what
  the association will look like for an out of source build:</p>

  <pre>hello/  ~~>      hello-out/                   &lt;~~  hello-out/
│                {                                 │
│                  src_root = .../hello/           │
│                  out_root = .../hello-out/       │
│                                                  │
│                  src_base = .../hello/           │
│                  out_base = .../hello-out/       │
│                                                  │
└── hello/  ~~>    hello/                     &lt;~~  └── hello/
                   {
                     src_base = .../hello/hello/
                     out_base = .../hello-out/hello/
                   }
                 }</pre>

  <p>Now that we have some scopes and variables to play with, it's a good time
  to introduce variable expansion. To get the value stored in a variable we
  use <code>$</code> followed by the variable's name. The variable is first
  looked up in the current scope (that is, the scope in which the expansion
  was encountered) and, if not found, in the outer scopes all the way to the
  global scope.</p>

  <div class="note">
  <p>To be precise, this is for the default <i>variable visibility</i>.
  Variables, however, can have more limited visibilities, such as
  <i>project</i>, <i>scope</i>, <i>target</i>, or <i>prerequisite</i>.</p>
  </div>

  <p>To illustrate the lookup semantics, let's add the following line to each
  <code>buildfile</code> in our <code>hello</code> project:</p>

  <pre>$ cd hello/  # Change to project root.

$ cat buildfile
...
info "src_base: $src_base"

$ cat hello/buildfile
...
info "src_base: $src_base"</pre>

  <p>And then build it:</p>

  <pre>$ b
buildfile:3:1: info: src_base: /tmp/hello/
hello/buildfile:8:1: info: src_base: /tmp/hello/hello/</pre>

  <p>In this case <code>src_base</code> is defined in each of the two scopes
  and we get their respective values. If, however, we change the above line to
  print <code>src_root</code> instead of <code>src_base</code>, we will get
  the same value from the root scope:</p>

  <pre>buildfile:3:1: info: src_root: /tmp/hello/
hello/buildfile:8:1: info: src_root: /tmp/hello/</pre>

  <div class="note">
  <p>In this section we've only scratched the surface when it comes to
  variables. In particular, variables and variable values in
  <code>build2</code> are optionally typed (those <code>[string]</code>,
  <code>[uint64]</code> we've seen in the build state dump). And in certain
  contexts the lookup semantics actually starts from the target, not from the
  scope (target-specific variables; there are also prerequisite-specific).
  These and other variable-related topics will be covered in subsequent
  sections.</p>
  </div>

  <p>One typical place to find <code>src/out_root</code> expansions is in the
  include search path options. For example, the source subdirectory
  <code>buildfile</code> generated by <a
  href="../../bdep/doc/bdep-new.xhtml"><code><b>bdep-new(1)</b></code></a> for
  an executable project actually looks like this (<code>poptions</code> stands
  for <i>preprocessor options</i>):</p>

  <pre>exe{hello}: {hxx cxx}{**}

cxx.poptions =+ "-I$out_root" "-I$src_root"</pre>

  <div class="note">
  <p>The strange-looking <code>=+</code> line is a <i>prepend</i> variable
  assignment. It adds the value on the right hand side to the beginning of the
  existing value. So, in the above example, the two header search paths will
  be added before any of the existing preprocessor options (and thus will be
  considered first).</p>

  <p>There are also the <i>append</i> assignment, <code>+=</code>, which adds
  the value on the right hand side to the end of the existing value, as well
  as, of course, the normal or <i>replace</i> assignment, <code>=</code>,
  which replaces the existing value with the right hand side. One way to
  remember where the existing and new values end up in the <code>=+</code> and
  <code>+=</code> results is to imagine the new value taking the position of
  <code>=</code> and the existing value &#8211; of <code>+</code>.</p>
  </div>

  <p>The above <code>buildfile</code> allows us to include our headers using
  the project's name as a prefix, inline with the <a
  href="../../build2-toolchain/doc/build2-toolchain-intro.xhtml#proj-struct">Canonical
  Project Structure</a> guidelines. For example, if we added the
  <code>utility.hxx</code> header to our <code>hello</code> project, we would
  include it like this:</p>

  <pre>#include &lt;iostream>

#include &lt;hello/utility.hxx>

int main ()
{
...
}</pre>

  <div class="note">
  <p>Besides <code>poptions</code>, there are also <code>coptions</code>
  (compile options), <code>loptions</code> (link options),
  <code>aoptions</code> (archive options) and <code>libs</code> (extra
  libraries to link). If you are familiar with <code>make</code>, these are
  roughly equivalent to <code>CPPFLAGS</code>,
  <code>CFLAGS</code>/<code>CXXFLAGS</code>, <code>LDFLAGS</code>,
  <code>ARFLAGS</code>, and <code>LIBS</code>/<code>LDLIBS</code>,
  respectively. Here they are again in the tabular form:</p>

  <pre>*.poptions   preprocess        CPPFLAGS
*.coptions   compile           CFLAGS/CXXFLAGS
*.loptions   link              LDFLAGS
*.aoptions   archive           ARFLAGS
*.libs       extra libraries   LIBS/LDLIBS</pre>

  <p>More specifically, there are three sets of these variables:
  <code>cc.*</code> (stands for <i>C-common</i>) which applies to all C-like
  languages as well as <code>c.*</code> and <code>cxx.*</code> which only
  apply during the C and C++ compilation, respectively. We can use these
  variables in our <code>buildfiles</code> to adjust the compiler/linker
  behavior. For example:</p>

  <pre>if ($cc.class == 'gcc')
{
  cc.coptions  += -fno-strict-aliasing  # C and C++
  cxx.coptions += -fno-exceptions       # only C++
}

if ($c.target.class != 'windows')
  c.libs += -ldl  # only C</pre>

  <p>Additionally, as we will see in <a
  href="#intro-operations-config">Configuring</a>, there are also the
  <code>config.cc.*</code>, <code>config.c.*</code>, and
  <code>config.cxx.*</code> sets which are used by the users of our projects
  to provide external configuration. The initial values of the
  <code>cc.*</code>, <code>c.*</code>, and <code>cxx.*</code> variables are
  taken from the corresponding <code>config.*.*</code> values.</p>

  <p>And, as we will learn in <a href="#intro-lib">Library Exportation</a>,
  there are also the <code>cc.export.*</code>, <code>c.export.*</code>, and
  <code>cxx.export.*</code> sets that are used to specify options that should
  be exported to the users of our library.</p>

  <p>If we adjust the <code>cc.*</code>, <code>c.*</code>, and
  <code>cxx.*</code> variables at the scope level, as in the above fragment,
  then the changes will apply when building every target in this scope (as
  well as in the nested scopes, if any). Usually this is what we want but
  sometimes we may need to pass additional options only when compiling certain
  source files or linking certain libraries or executables. For that we use
  the target-specific variable assignment. For example:</p>

  <pre>exe{hello}: {hxx cxx}{**}

obj{utility}: cxx.poptions += -DNDEBUG
exe{hello}: cxx.loptions += -static</pre>

  <p>Note that we set these variables on targets which they affect. In
  particular, those with a background in other build systems may, for example,
  erroneously expect that setting <code>poptions</code> on a library target
  will affect compilation of its prerequisites. For example, the following
  does not work:</p>

  <pre>exe{hello}: cxx.poptions += -DNDEBUG</pre>

  <p>The recommended way to achieve this behavior in <code>build2</code> is to
  organize your targets into subdirectories, in which case we can just set the
  variables on the scope. And if this is impossible or undesirable, then we
  can use target type/pattern-specific variables (if there is a common
  pattern) or simply list the affected targets explicitly. For example:</p>

  <pre>obj{*.test}: cxx.poptions += -DDEFINE_MAIN
obj{main utility}: cxx.poptions += -DNDEBUG</pre>

  <p>The first line covers compilation of source files that have the
  <code>.test</code> second-level extension (see <a
  href="#intro-unit-test">Implementing Unit Testing</a> for background) while
  the second simply lists the targets explicitly.</p>

  <p>It is also possible to specify different options when producing different
  types of object files (<code>obje{}</code> &#8211; executable,
  <code>obja{}</code> &#8211; static library, or <code>objs{}</code> &#8211;
  shared library) or when linking different libraries (<code>liba{}</code>
  &#8211; static library or <code>libs{}</code> &#8211; shared library). See
  <a href="#intro-lib">Library Exportation and Versioning</a> for an
  example.</p>
  </div>

  <p>As mentioned above, each <code>buildfile</code> in a project is loaded
  into its corresponding scope. As a result, we rarely need to open scopes
  explicitly. In the few cases that we do, we use the following syntax:</p>

  <pre>&lt;directory>/
{
  ...
}</pre>

  <p>If the scope directory is relative, then it is assumed to be relative to
  the current scope. As an exercise for understanding, let's reimplement our
  <code>hello</code> project as a single <code>buildfile</code>. That is, we
  move the contents of the source subdirectory <code>buildfile</code> into the
  root <code>buildfile</code>:</p>

  <pre>$ tree hello/
hello/
├── build/
│   └── ...
├── hello/
│   └── hello.cxx
└── buildfile

$ cat hello/buildfile

./: hello/

hello/
{
  ./: exe{hello}: {hxx cxx}{**}
}</pre>

  <div class="note">
  <p>While this single <code>buildfile</code> setup is not recommended for new
  projects, it can be useful for non-intrusive conversion of existing projects
  to <code>build2</code>. One approach is to place the unmodified original
  project into a subdirectory (potentially automating this with a mechanism
  such as <code>git(1)</code> submodules) then adding the <code>build/</code>
  subdirectory and the root <code>buildfile</code> which explicitly opens
  scopes to define the build over the upstream project's subdirectory
  structure.</p>
  </div>

  <p>Seeing this merged <code>buildfile</code> may make you wonder what
  exactly caused the loading of the source subdirectory <code>buildfile</code>
  in our normal setup. In other words, when we build our <code>hello</code>
  from the project root, who loads <code>hello/buildfile</code> and why?</p>

  <p>Actually, in the earlier days of <code>build2</code>, we had to
  explicitly load <code>buildfiles</code> that define targets we depend on
  with the <code>include</code> directive. In fact, we still can (and have to
  if we are depending on targets other than directories). For example:</p>

  <pre>./: hello/

include hello/buildfile</pre>

  <p>We can also omit <code>buildfile</code> for brevity and have just:</p>

  <pre>include hello/</pre>

  <p>This explicit inclusion, however, quickly becomes tiresome as the number
  of directories grows. It also makes using wildcard patterns for subdirectory
  prerequisites a lot less appealing.</p>

  <p>To overcome this the <code>dir{}</code> target type implements an
  interesting prerequisite to target resolution semantics: if there is no
  existing target with this name, a <code>buildfile</code> that (presumably)
  defines this target is automatically loaded from the corresponding
  directory. In fact, this mechanism goes a step further and, if the
  <code>buildfile</code> does not exist, then it assumes one with the
  following contents was implied:</p>

  <pre>./: */</pre>

  <p>That is, it simply builds all the subdirectories. This is especially
  handy when organizing related tests into directory hierarchies.</p>

  <div class="note">
  <p>As mentioned above, this automatic inclusion is only triggered if the
  target we depend on is <code>dir{}</code> and we still have to explicitly
  include the necessary <code>buildfiles</code> for other targets. One common
  example is a project consisting of a library and an executable that links
  it, each residing in a separate directory next to each other (as noted
  earlier, this is not recommended for projects that you plan to package). For
  example:</p>

  <pre>hello/
├── build/
│   └── ...
├── hello/
│   ├── main.cxx
│   └── buildfile
├── libhello/
│   ├── hello.hxx
│   ├── hello.cxx
│   └── buildfile
└── buildfile</pre>

  <p>In this case the executable <code>buildfile</code> would look along these
  lines:</p>

  <pre>include ../libhello/ # Include lib{hello}.

exe{hello}: {hxx cxx}{**} ../libhello/lib{hello}</pre>

  <p>Note also that <code>buildfile</code> inclusion should only be used for
  accessing targets within the same project. For cross-project references we
  use <a href="#intro-import">Target Importation</a>.</p>
  </div>

  <h2 id="intro-operations">1.4 Operations</h2>

  <p>Modern build systems have to perform operations other than just building:
  cleaning the build output, running tests, installing/uninstalling the build
  results, preparing source distributions, and so on. And, if the build system
  has integrated configuration support, configuring the project would
  naturally belong to this list as well.</p>

  <div class="note">
  <p>If you are familiar with <code>make</code>, you should recognize the
  parallel with the common <code>clean</code> <code>test</code>,
  <code>install</code>, and <code>dist</code>, "operation" pseudo-targets.</p>
  </div>

  <p>In <code>build2</code> we have the concept of a <i>build system
  operation</i> performed on a target. The two pre-defined operations are
  <code>update</code> and <code>clean</code> with other operations provided by
  build system modules.</p>

  <p>Operations to be performed and targets to perform them on are specified
  on the command line. As discussed earlier, <code>update</code> is the
  default operation and <code>./</code> in the current directory is the
  default target if no operation and/or target is specified explicitly. And,
  similar to targets, we can specify multiple operations (not necessarily on
  the same target) in a single build system invocation. The list of operations
  to perform and targets to perform them on is called a <i>build
  specification</i> or <i>buildspec</i> for short (see <a
  href="b.xhtml"><code><b>b(1)</b></code></a> for details). Here are a few
  examples:</p>

  <pre>$ cd hello        # Change to project root.

$ b               # Update current directory.
$ b ./            # Same as above.
$ b update        # Same as above.
$ b update: ./    # Same as above.

$ b clean update  # Rebuild.

$ b clean:  hello/             # Clean specific target.
$ b update: hello/exe{hello}   # Update specific target

$ b update: libhello/ tests/   # Update two targets.</pre>

  <div class="note">
  <p>If you are running <code>build2</code> from PowerShell, then you will
  need to use quoting when updating specific targets, for example:</p>

  <pre>$ b update: 'hello/exe{hello}'</pre>
  </div>

  <p>Let's revisit <code>build/bootstrap.build</code> from our
  <code>hello</code> project:</p>

  <pre>project = hello

using version
using config
using test
using install
using dist</pre>

  <p>Other than <code>version</code>, all the modules we load define new
  operations. Let's examine each of them starting with
  <code>config</code>.</p>

  <h3 id="intro-operations-config">1.4.1 Configuring</h3>

  <p>As mentioned briefly earlier, the <a
  href="#module-config"><code>config</code></a> module provides support for
  persisting configurations by having us <i>configure</i> our projects. At
  first it may feel natural to call <code>configure</code> an operation. There
  is, however, a conceptual problem: we don't really configure a target. And,
  perhaps after some meditation, it should become clear that what we are
  really doing is configuring operations on targets. For example, configuring
  updating a C++ project might involve detecting and saving information about
  the C++ compiler while configuring installing it may require specifying the
  installation directory.</p>

  <p>In other words, <code>configure</code> is an operation on operation on
  targets &#8211; a meta-operation.  And so in <code>build2</code> we have the
  concept of a <i>build system meta-operation</i>.  If not specified
  explicitly (as part of the buildspec), the default is <code>perform</code>,
  which is to simply perform the operation.</p>

  <p>Back to <code>config</code>, this module provides two meta-operations:
  <code>configure</code> which saves the configuration of a project into the
  <code>build/config.build</code> file as well as <code>disfigure</code> which
  removes it.</p>

  <div class="note">
  <p>While the common meaning of the word <i>disfigure</i> is somewhat
  different to what we make it mean in this context, we still prefer it over
  the commonly suggested alternative (<i>deconfigure</i>) for the symmetry of
  their Latin <i>con-</i> ("together") and <i>dis-</i> ("apart") prefixes.</p>
  </div>

  <p>Let's say for the in source build of our <code>hello</code> project we
  want to use <code>Clang</code> and enable debug information. Without
  persistence we would have to repeat this configuration on every build system
  invocation:</p>

  <pre>$ cd hello/  # Change to project root.

$ b config.cxx=clang++ config.cxx.coptions=-g</pre>

  <p>Instead, we can configure our project with this information once and from
  then on invoke the build system without any arguments:</p>

  <pre>$ b configure config.cxx=clang++ config.cxx.coptions=-g

$ tree ./
./
├── build/
│   ├── ...
│   └── config.build
└── ...

$ b
$ b clean
$ b
...</pre>

  <p>To remove the persistent configuration we use the <code>disfigure</code>
  meta-operation:</p>

  <pre>$ b disfigure</pre>

  <p>Let's again configure our project and take a look at
  <code>config.build</code>:</p>

  <pre>$ b configure config.cxx=clang++ config.cxx.coptions=-g

$ cat build/config.build

config.cxx = clang++
config.cxx.poptions = [null]
config.cxx.coptions = -g
config.cxx.loptions = [null]
config.cxx.aoptions = [null]
config.cxx.libs = [null]
...</pre>

  <p>As you can see, it's just a buildfile with a bunch of variable
  assignments. In particular, this means you can tweak your build
  configuration by modifying this file with your favorite editor. Or,
  alternatively, you can adjust the configuration by reconfiguring the
  project:</p>

  <pre>$ b configure config.cxx=g++

$ cat build/config.build

config.cxx = g++
config.cxx.poptions = [null]
config.cxx.coptions = -g
config.cxx.loptions = [null]
config.cxx.aoptions = [null]
config.cxx.libs = [null]
...</pre>

  <p>Any variable value specified on the command line overrides those
  specified in the <code>buildfiles</code>. As a result,
  <code>config.cxx</code> was updated while the value of
  <code>config.cxx.coptions</code> was preserved.</p>

  <div class="note">
  <p>To revert a configuration variable to its default value, list its name in
  the special <code>config.config.disfigure</code> variable. For example:</p>

  <pre>$ b configure config.config.disfigure=config.cxx</pre>
  </div>

  <p>Command line variable overrides are also handy to adjust the
  configuration for a single build system invocation. For example, let's say
  we want to quickly check that our project builds with optimization but
  without permanently changing the configuration:</p>

  <pre>$ b config.cxx.coptions=-O3  # Rebuild with -O3.
$ b                          # Rebuild with -g.</pre>

  <div class="note">
  <p>Besides the various <code>*.?options</code> variables, we can also
  specify the "compiler mode" options as part of the compiler executable in
  <code>config.c</code> and <code>config.cxx</code>. Such options cannot be
  modified by buildfiles and they will appear last on the command lines. For
  example:</p>

  <pre>$ b configure config.cxx="g++ -m32"</pre>

  <p>The compiler mode options are also the correct place to specify
  <i>system-like</i> header (<code>-I</code>) and library (<code>-L</code>,
  <code>/LIBPATH</code>) search paths. Where by system-like we mean common
  installation directories like <code>/usr/include</code> or
  <code>/usr/local/lib</code> which may contain older versions of the
  libraries we are trying to build and/or use. By specifying these paths as
  part of the mode options (as opposed to <code>config.*.poptions</code> and
  <code>config.*.loptions</code>) we make sure they will be considered last,
  similar to the compiler's build-in search paths. For example:</p>

  <pre>$ b configure config.cxx="g++ -L/opt/install"</pre>
  </div>

  <p>If we would like to prevent subsequent changes to the environment from
  affecting our build configuration, we can make it <i>hermetic</i> (see <a
  href="#module-config-hermetic">Hermetic Build Configurations</a> for
  details):</p>

  <pre>$ b configure config.config.hermetic=true ...</pre>

  <div class="note">
  <p>One prominent use of hermetic configurations is to preserve the build
  environment of the Visual Studio development command prompt. That is,
  hermetically configuring our project in a suitable Visual Studio command
  prompt makes us free to build it from any other prompt or shell, IDE,
  etc.</p>
  </div>

  <p>We can also configure out of source builds of our projects. In this case,
  besides <code>config.build</code>, <code>configure</code> also saves the
  location of the source directory so that we don't have to repeat that
  either. Remember, this is how we used to build our <code>hello</code> out of
  source:</p>

  <pre>$ b hello/@hello-gcc/   config.cxx=g++
$ b hello/@hello-clang/ config.cxx=clang++</pre>

  <p>And now we can do:</p>

  <pre>$ b configure: hello/@hello-gcc/   config.cxx=g++
$ b configure: hello/@hello-clang/ config.cxx=clang++

$ hello-clang/
hello-clang/
└── build/
    ├── bootstrap/
    │   └── src-root.build
    └── config.build

$ b hello-gcc/
$ b hello-clang/
$ b hello-gcc/ hello-clang/</pre>

  <p>One major benefit of an in source build is the ability to run executables
  as well as examine build and test output (test results, generated source
  code, documentation, etc) without leaving the source directory.
  Unfortunately, we cannot have multiple in source builds and as was discussed
  earlier, mixing in and out of source builds is not recommended.</p>

  <p>To overcome this limitation <code>build2</code> has a notion of
  <i>forwarded configurations</i>. As the name suggests, we can configure a
  project's source directory to forward to one of its out of source builds.
  Once done, whenever we run the build system from the source directory, it
  will automatically build in the corresponded forwarded output directory.
  Additionally, it will <i>backlink</i> (using symlinks or another suitable
  mechanism) certain "interesting" targets (<code>exe{}</code>,
  <code>doc{}</code>) to the source directory for easy access. As an example,
  let's configure our <code>hello/</code> source directory to forward to the
  <code>hello-gcc/</code> build:</p>

  <pre>$ b configure: hello/@hello-gcc/,forward

$ cd hello/  # Change to project root.
$ b
c++ hello/cxx{hello} -> ../hello-gcc/hello/obje{hello}
ld ../hello-gcc/hello/exe{hello}
ln ../hello-gcc/hello/exe{hello} -> hello/</pre>

  <p>Notice the last line in the above listing: it indicates that
  <code>exe{hello</code>} from the out directory was backlinked in our
  project's source subdirectory:</p>

  <pre>$ tree ./
./
├── build/
│   ├── bootstrap/
│   │   └── out-root.build
│   └── ...
├── hello/
│   ├── ...
│   └── hello -> ../../hello-gcc/hello/hello*
└── ...

$ ./hello/hello
Hello World!</pre>

  <div class="note">
  <p>By default only <code>exe{}</code> and <code>doc{}</code> targets are
  backlinked. This, however, can be customized with the <code>backlink</code>
  target-specific variable.</p>
  </div>

  <h3 id="intro-operations-test">1.4.2 Testing</h3>

  <p>The next module we load in <code>bootstrap.build</code> is <a
  href="#module-test"><code>test</code></a> which defines the
  <code>test</code> operation. As the name suggests, this module provides
  support for running tests.</p>

  <p>There are two types of tests that we can run with the <code>test</code>
  module: simple and scripted.</p>

  <p>A simple test is just an executable target with the <code>test</code>
  target-specific variable set to <code>true</code>. For example:</p>

  <pre>exe{hello}: test = true</pre>

  <p>A simple test is executed once and in its most basic form (typical for
  unit testing) doesn't take any inputs nor produce any output, indicating
  success via the zero exit status. If we test our <code>hello</code> project
  with the above addition to the <code>buildfile</code>, then we will see the
  following output:</p>

  <pre>$ b test
test hello/exe{hello}
Hello, World!</pre>

  <p>While the test passes (since it exited with zero status), we probably
  don't want to see that <code>Hello, World!</code> every time we run it (this
  can, however, be quite useful when running examples). More importantly, we
  don't really test its functionality and if tomorrow our <code>hello</code>
  starts swearing rather than greeting, the test will still pass.</p>

  <p>Besides checking its exit status we can also supply some basic
  information to a simple test (more common for integration testing).
  Specifically, we can pass command line options (<code>test.options</code>)
  and arguments (<code>test.arguments</code>) as well as input
  (<code>test.stdin</code>, used to supply test's <code>stdin</code>) and
  output (<code>test.stdout</code>, used to compare to test's
  <code>stdout</code>).</p>

  <p>Let's see how we can use this to fix our <code>hello</code> test by
  making sure our program prints the expected greeting. First, we need to add
  a file that will contain the expected output, let's call it
  <code>test.out</code>:</p>

  <pre>$ ls -1 hello/
hello.cxx
test.out
buildfile

$ cat hello/test.out
Hello, World!</pre>

  <p>Next, we arrange for it to be compared to our test's <code>stdout</code>.
  Here is the new <code>hello/buildfile</code>:</p>

  <pre>exe{hello}: {hxx cxx}{**}
exe{hello}: file{test.out}: test.stdout = true</pre>

  <p>The last line looks new. What we have here is a <i>prerequisite-specific
  variable</i> assignment. By setting <code>test.stdout</code> for the
  <code>file{test.out}</code> prerequisite of target <code>exe{hello}</code>
  we mark it as expected <code>stdout</code> output of <i>this</i> target
  (theoretically, we could have marked it as <code>test.input</code> for
  another target). Notice also that we no longer need the <code>test</code>
  target-specific variable; it's unnecessary if one of the other
  <code>test.*</code> variables is specified.</p>

  <p>Now, if we run our test, we won't see any output:</p>

  <pre>$ b test
test hello/exe{hello}</pre>

  <p>And if we try to change the greeting in <code>hello.cxx</code> but not in
  <code>test.out</code>, our test will fail printing the <code>diff(1)</code>
  comparison of the expected and actual output:</p>

  <pre>$ b test
c++ hello/cxx{hello} -> hello/obje{hello}
ld hello/exe{hello}
test hello/exe{hello}
--- test.out
+++ -
@@ -1 +1 @@
-Hello, World!
+Hi, World!
error: test hello/exe{hello} failed</pre>

  <p>Notice another interesting thing: we have modified <code>hello.cxx</code>
  to change the greeting and our test executable was automatically rebuilt
  before testing. This happened because the <code>test</code> operation
  performs <code>update</code> as its <i>pre-operation</i> on all the targets
  to be tested.</p>

  <p>Let's make our <code>hello</code> program more flexible by accepting the
  name to greet on the command line:</p>

  <pre>#include &lt;iostream>

int main (int argc, char* argv[])
{
  if (argc &lt; 2)
  {
    std::cerr &lt;&lt; "error: missing name" &lt;&lt; std::endl;
    return 1;
  }

  std::cout &lt;&lt; "Hello, " &lt;&lt; argv[1] &lt;&lt; '!' &lt;&lt; std::endl;
}</pre>

  <p>We can exercise its successful execution path with a simple test fairly
  easily:</p>

  <pre>exe{hello}: test.arguments = 'World'
exe{hello}: file{test.out}: test.stdout = true</pre>

  <p>What if we also wanted to test its error handling? Since simple tests are
  single-run, this won't be easy. Even if we could overcome this, having
  expected output for each test in a separate file will quickly become untidy.
  And this is where script-based tests come in. Testscript is
  <code>build2</code>'s portable language for running tests. It vaguely
  resembles Bash and is optimized for concise test implementation and fast,
  parallel execution.</p>

  <p>Just to give you an idea (see <a
  href="build2-testscript-manual.xhtml#intro">Testscript Introduction</a> for
  a proper introduction), here is what testing our <code>hello</code> program
  with Testscript would look like:</p>

  <pre>$ ls -1 hello/
hello.cxx
testscript
buildfile

$ cat hello/buildfile

exe{hello}: {hxx cxx}{**} testscript</pre>

  <p>And this is the contents of <code>hello/testscript</code>:</p>

  <pre>: basics
:
$* 'World' >'Hello, World!'

: missing-name
:
$* 2>>EOE != 0
error: missing name
EOE</pre>

  <p>A couple of key points: The <code>test.out</code> file is gone with all
  the test inputs and expected outputs incorporated into
  <code>testscript</code>. To test an executable with Testscript, all we have
  to do is list the corresponding <code>testscript</code> file as its
  prerequisite (and which, being a fixed name, doesn't need an explicit target
  type, similar to <code>manifest</code>).</p>

  <p>To see Testscript in action, let's say we've made our program more
  forgiving by falling back to a default name if one wasn't specified:</p>

  <pre>#include &lt;iostream>

int main (int argc, char* argv[])
{
  const char* n (argc > 1 ? argv[1] : "World");
  std::cout &lt;&lt; "Hello, " &lt;&lt; n &lt;&lt; '!' &lt;&lt; std::endl;
}</pre>

  <p>If we forget to adjust the <code>missing-name</code> test, then this is
  what we could expect to see when running the tests:</p>

  <pre>b test
c++ hello/cxx{hello} -> hello/obje{hello}
ld hello/exe{hello}
test hello/exe{hello} + hello/testscript{testscript}
hello/testscript:7:1: error: hello/hello exit code 0 == 0
  info: stdout: hello/test-hello/missing-name/stdout</pre>

  <p>Testscript-based integration testing is the default setup for executable
  (<code>-t&#160;exe</code>) projects created by <a
  href="../../bdep/doc/bdep-new.xhtml"><code><b>bdep-new(1)</b></code></a>.
  Here is the recap of the overall layout:</p>

  <pre>hello/
├── build/
│   └── ...
├── hello/
│   ├── hello.cxx
│   ├── testscript
│   └── buildfile
├── buildfile
└── manifest</pre>

  <p>For libraries (<code>-t&#160;lib</code>), however, the integration
  testing setup is a bit different. Here are the relevant parts of the
  layout:</p>

  <pre>libhello/
├── build/
│   └── ...
├── libhello/
│   ├── hello.hxx
│   ├── hello.cxx
│   ├── export.hxx
│   ├── version.hxx.in
│   └── buildfile
├── tests/
│   ├── build/
│   │   ├── bootstrap.build
│   │   └── root.build
│   ├── basics/
│   │   ├── driver.cxx
│   │   └── buildfile
│   └── buildfile
├── buildfile
└── manifest</pre>

  <p>Specifically, there is no <code>testscript</code> in
  <code>libhello/</code>, the project's source subdirectory. Instead, we have
  the <code>tests/</code> subdirectory which itself looks like a project: it
  contains the <code>build/</code> subdirectory with all the familiar files,
  etc. In fact, <code>tests</code> is a <i>subproject</i> of our
  <code>libhello</code> project.</p>

  <p>While we will be examining <code>tests</code> in greater detail later, in
  a nutshell, the reason it is a subproject is to be able to test an installed
  version of our library. By default, when <code>tests</code> is built as part
  of its parent project (called <i>amalgamation</i>), the locally built
  <code>libhello</code> library will be automatically imported. However, we
  can also configure a build of <code>tests</code> out of its amalgamation, in
  which case we can import an installed version of <code>libhello</code>. We
  will learn how to do all that as well as the underlying concepts
  (<i>subproject</i>/<i>amalgamation</i>, <i>import</i>, etc) in the coming
  sections.</p>

  <p>Inside <code>tests/</code> we have the <code>basics/</code> subdirectory
  which contains a simple test for our library's API. By default it doesn't
  use Testscript but if you want to, you can. You can also rename
  <code>basics/</code> to something more meaningful and add more tests next to
  it. For example, if we were creating an XML parsing and serialization
  library, then our <code>tests/</code> could have the following layout:</p>

  <pre>tests/
├── build/
│   └── ...
├── parser/
│   └── ...
├── serializer/
│   └── ...
└── buildfile</pre>

  <div class="note">
  <p>Nothing prevents us from having the <code>tests/</code> subdirectory for
  executable projects. And it can be just a subdirectory or a subproject, the
  same as for libraries. Making it a subproject makes sense if your program
  has complex installation, for example, if its execution requires
  configuration and/or data files that need to be found, etc. For simple
  programs, however, testing the executable before installing it is usually
  sufficient.</p>

  <p>For a general discussion of functional/integration and unit testing refer
  to the <a
  href="../../build2-toolchain/doc/build2-toolchain-intro.xhtml#proj-struct-tests">Tests</a>
  section in the toolchain introduction. For details on the unit test support
  implementation see <a href="#intro-unit-test">Implementing Unit
  Testing</a>.</p>
  </div>

  <h3 id="intro-operations-install">1.4.3 Installing</h3>

  <p>The <a href="#module-install"><code>install</code></a> module defines the
  <code>install</code> and <code>uninstall</code> operations.  As the name
  suggests, this module provides support for project installation.</p>

  <div class="note">
  <p>Installation in <code>build2</code> is modeled after UNIX-like operation
  systems though the installation directory layout is highly customizable.
  While <code>build2</code> projects can import <code>build2</code> libraries
  directly, installation is often a way to "export" them in a form usable by
  other build systems.</p>
  </div>

  <p>The root installation directory is specified with the
  <code>config.install.root</code> configuration variable. Let's install our
  <code>hello</code> program into <code>/tmp/install</code>:</p>

  <pre>$ cd hello/  # Change to project root.

$ b install config.install.root=/tmp/install/</pre>

  <p>And see what we've got (executables are marked with <code>*</code>):</p>

  <pre>$ tree /tmp/install/

/tmp/install/
├── bin/
│   └── *hello
└── share/
    └── doc/
        └── hello/
            └── manifest</pre>

  <p>Similar to the <code>test</code> operation, <code>install</code> performs
  <code>update</code> as a pre-operation for targets that it installs.</p>

  <div class="note">
  <p>We can also configure our project with the desired
  <code>config.install.*</code> values so that we don't have to repeat them on
  every install/uninstall. For example:</p>

  <pre>$ b configure config.install.root=/tmp/install/
$ b install
$ b uninstall</pre>
  </div>

  <p>Now let's try the same for <code>libhello</code> (symbolic link targets
  are shown with <code>-></code> and actual static/shared library names may
  differ on your operating system):</p>

  <pre>$ rm -r /tmp/install

$ cd libhello/  # Change to project root.

$ b install config.install.root=/tmp/install/

$ tree /tmp/install/

/tmp/install/
├── include/
│   └── libhello/
│       ├── hello.hxx
│       ├── export.hxx
│       └── version.hxx
├── lib/
│   ├── pkgconfig/
│   │   ├── libhello.pc
│   │   ├── libhello.shared.pc
│   │   └── libhello.static.pc
│   ├── libhello.a
│   ├── libhello.so -> libhello-0.1.so
│   └── libhello-0.1.so
└── share/
    └── doc/
        └── libhello/
            └── manifest</pre>

  <p>As you can see, the library headers go into the customary
  <code>include/</code> subdirectory while static and shared libraries (and
  their <code>pkg-config(1)</code> files) &#8211; into <code>lib/</code>.
  Using this installation we should be able to import this library from other
  build systems or even use it in a manual build:</p>

  <pre>$ g++ -I/tmp/install/include -L/tmp/install/lib greet.cxx -lhello</pre>

  <p>If we want to install into a system-wide location like <code>/usr</code>
  or <code>/usr/local</code>, then we most likely will need to specify the
  <code>sudo(1)</code> program:</p>

  <pre>$ b config.install.root=/usr/local/ config.install.sudo=sudo</pre>

  <div class="note">
  <p>In <code>build2</code> only actual install/uninstall commands are
  executed with <code>sudo(1)</code>. And while on the topic of sensible
  implementations, <code>uninstall</code> can be generally trusted to work
  reliably.</p>
  </div>

  <p>The default installability of a target as well as where it is installed
  is determined by its target type. For example, <code>exe{}</code> is by
  default installed into <code>bin/</code>, <code>doc{}</code> &#8211; into
  <code>share/doc/&lt;project>/</code>, and <code>file{}</code> is not
  installed.</p>

  <p>We can, however, override these defaults with the <code>install</code>
  target-specific variable.  Its value should be either special
  <code>false</code> indicating that the target should not be installed or the
  directory to install the target to. As an example, here is what the root
  <code>buildfile</code> from our <code>libhello</code> project looks
  like:</p>

  <pre>./: {*/ -build/} manifest

tests/: install = false</pre>

  <p>The first line we have already seen and the purpose of the second line
  should now be clear: it makes sure we don't try to install anything in the
  <code>tests/</code> subdirectory.</p>

  <p>If the value of the <code>install</code> variable is not
  <code>false</code>, then it is normally a relative path with the first path
  component being one of these names:</p>

  <pre>name          default                        override
----          -------                        --------
root                                         config.install.root

data_root     root/                          config.install.data_root
exec_root     root/                          config.install.exec_root

bin           exec_root/bin/                 config.install.bin
sbin          exec_root/sbin/                config.install.sbin
lib           exec_root/lib/                 config.install.lib
libexec       exec_root/libexec/&lt;project>/   config.install.libexec
pkgconfig     lib/pkgconfig/                 config.install.pkgconfig

etc           data_root/etc/                 config.install.etc
include       data_root/include/             config.install.include
include_arch  include/                       config.install.include_arch
share         data_root/share/               config.install.share
data          share/&lt;project>/               config.install.data
buildfile     share/build2/export/&lt;project>/ config.install.buildfile

doc           share/doc/&lt;project>/           config.install.doc
legal         doc/                           config.install.legal
man           share/man/                     config.install.man
man&lt;N>        man/man&lt;N>/                    config.install.man&lt;N></pre>

  <p>Let's see what's going on here: The default install directory tree is
  derived from the <code>config.install.root</code> value but the location of
  each node in this tree can be overridden by the user that installs our
  project using the corresponding <code>config.install.*</code> variables (see
  the <a href="#module-install"><code>install</code></a> module documentation
  for details on their meaning). In our <code>buildfiles</code>, in turn, we
  use the node names instead of actual directories. As an example, here is a
  <code>buildfile</code> fragment from the source subdirectory of our
  <code>libhello</code> project:</p>

  <pre>hxx{*}:
{
  install         = include/libhello/
  install.subdirs = true
}</pre>

  <p>Here we set the installation location for headers to be the
  <code>libhello/</code> subdirectory of the <code>include</code> installation
  location. Assuming <code>config.install.root</code> is <code>/usr/</code>,
  the <code>install</code> module will perform the following steps to resolve
  this relative path to the actual, absolute installation directory:</p>

  <pre>include/libhello/
data_root/include/libhello/
root/include/libhello/
/usr/include/libhello/</pre>

  <p>In the above <code>buildfile</code> fragment we also see the use of the
  <code>install.subdirs</code> variable. Setting it to <code>true</code>
  instructs the <code>install</code> module to recreate subdirectories
  starting from this point in the project's directory hierarchy. For example,
  if our <code>libhello/</code> source subdirectory had the
  <code>details/</code> subdirectory with the <code>utility.hxx</code> header,
  then this header would have been installed as
  <code>.../include/libhello/details/utility.hxx</code>.</p>

  <div class="note">
  <p>By default the generated <code>pkg-config</code> files will contain
  <code>install.include</code> and <code>install.lib</code> directories as
  header (<code>-I</code>) and library (<code>-L</code>) search paths,
  respectively. However, these can be customized with the
  <code>{c,cxx}.pkgconfig.{include,lib}</code> variables. For example,
  sometimes we may need to install headers into a subdirectory of the include
  directory but include them without this subdirectory:</p>

  <pre># Install headers into hello/libhello/ subdirectory of, say,
# /usr/include/ but include them as &lt;libhello/*>.
#
hxx{*}:
{
  install         = include/hello/libhello/
  install.subdirs = true
}

lib{hello}: cxx.pkgconfig.include = include/hello/</pre>
  </div>

  <h3 id="intro-operations-dist">1.4.4 Distributing</h3>

  <p>The last module that we load in our <code>bootstrap.build</code> is
  <code>dist</code> which provides support for the preparation of source
  distributions and defines the <code>dist</code> meta-operation. Similar to
  <code>configure</code>, <code>dist</code> is a meta-operation rather than an
  operation because, conceptually, we are preparing a distribution for
  performing operations (like <code>update</code>, <code>test</code>) on
  targets rather than targets themselves.</p>

  <p>The preparation of a correct distribution requires that all the necessary
  project files (sources, documentation, etc) be listed as prerequisites in
  the project's <code>buildfiles</code>.</p>

  <div class="note">
  <p>You may wonder why not just use the export support offered by many
  version control systems? The main reason is that in most real-world projects
  version control repositories contain a lot more than what needs to be
  distributed. In fact, it is not uncommon to host multiple build system
  projects/packages in a single repository. As a result, with this approach we
  seem to inevitably end up maintaining an exclusion list, which feels
  backwards: why specify all the things we don't want in a new list instead of
  making sure the already existing list of things that we do want is complete?
  Also, once we have the complete list, it can be put to good use by other
  tools, such as editors, IDEs, etc.</p>
  </div>

  <p>The preparation of a distribution also requires an out of source build.
  This allows the <code>dist</code> module to distinguish between source and
  output targets. By default, targets found in src are included into the
  distribution while those in out are excluded. However, we can customize this
  with the <code>dist</code> target-specific variable.</p>

  <p>As an example, let's prepare a distribution of our <code>hello</code>
  project using the out of source build configured in <code>hello-out/</code>.
  We use <code>config.dist.root</code> to specify the directory to write the
  distribution to:</p>

  <pre>$ b dist: hello-out/ config.dist.root=/tmp/dist

$ ls -1 /tmp/dist
hello-0.1.0/

$ tree /tmp/dist/hello-0.1.0/
/tmp/dist/hello-0.1.0/
├── build/
│   ├── bootstrap.build
│   └── root.build
├── hello/
│   ├── hello.cxx
│   ├── testscript
│   └── buildfile
├── buildfile
└── manifest</pre>

  <p>As we can see, the distribution directory includes the project version
  (from the <code>version</code> variable which, in our case, is extracted
  from <code>manifest</code> by the <code>version</code> module). Inside the
  distribution directory we have our project's source files (but, for example,
  without any <code>.gitignore</code> files that we may have had in
  <code>hello/</code>).</p>

  <p>We can also ask the <code>dist</code> module to package the distribution
  directory into one or more archives and generate their checksum files for
  us. For example:</p>

  <pre>$ b dist: hello-out/ \
  config.dist.root=/tmp/dist \
  config.dist.archives="tar.gz zip" \
  config.dist.checksums=sha256

$ ls -1 /tmp/dist
hello-0.1.0/
hello-0.1.0.tar.gz
hello-0.1.0.tar.gz.sha256
hello-0.1.0.zip
hello-0.1.0.zip.sha256</pre>

  <div class="note">
  <p>We can also configure our project with the desired
  <code>config.dist.*</code> values so we don't have to repeat them every
  time. For example:</p>

  <pre>$ b configure: hello-out/ config.dist.root=/tmp/dist ...
$ b dist</pre>
  </div>

  <p>Let's now take a look at an example of customizing what gets distributed.
  Most of the time you will be using this mechanism to include certain targets
  from out. Here is a fragment from the <code>libhello</code> source
  subdirectory <code>buildfile</code>:</p>

  <pre>hxx{version}: in{version} $src_root/manifest</pre>

  <p>Our library provides the <code>version.hxx</code> header that the users
  can include to obtain its version. This header is generated by the
  <code>version</code> module from the <code>version.hxx.in</code> template.
  In essence, the <code>version</code> module takes the version value from our
  <code>manifest</code>, splits it into various components (major, minor,
  patch, etc) and then preprocesses the <code>in{}</code> file substituting
  these values (see the <a href="#module-version"><code>version</code></a>
  module documentation for details). The end result is an automatically
  maintained version header.</p>

  <p>Usually there is no need to include this header into the distribution
  since it will be automatically generated if and when necessary. However, we
  can if we need to. For example, we could be porting an existing project and
  its users could be expecting the version header to be shipped as part of the
  archive. Here is how we can achieve this:</p>

  <pre>hxx{version}: in{version} $src_root/manifest
{
  dist = true
  clean = ($src_root != $out_root)
}</pre>

  <p>Because this header is an output target, we have to explicitly request
  its distribution with <code>dist=true</code>. Notice that we have also
  disabled its cleaning for the in source build so that the <code>clean</code>
  operation results in a state identical to distributed.</p>

  <h2 id="intro-import">1.5 Target Importation</h2>

  <p>Recall that if we need to depend on a target defined in another
  <code>buildfile</code> within our project, then we simply include the said
  <code>buildfile</code> and reference the target. For example, if our
  <code>hello</code> included both an executable and a library in separate
  subdirectories next to each other:</p>

  <pre>hello/
├── build/
│   └── ...
├── hello/
│   ├── ...
│   └── buildfile
└── libhello/
    ├── ...
    └── buildfile</pre>

  <p>Then our executable <code>buildfile</code> could look like this:</p>

  <pre>include ../libhello/ # Include lib{hello}.

exe{hello}: {hxx cxx}{**} ../libhello/lib{hello}</pre>

  <p>What if instead <code>libhello</code> were a separate project? The
  inclusion approach would no longer work for two reasons: we don't know the
  path to <code>libhello</code> (after all, it's an independent project and
  can reside anywhere) and we can't assume the path to the
  <code>lib{hello}</code> target within <code>libhello</code> (the project
  directory layout can change).</p>

  <p>To depend on a target from a separate project we use <i>importation</i>
  instead of inclusion. This mechanism is also used to depend on targets that
  are not part of any project, for example, installed libraries.</p>

  <p>The importing project's side is pretty simple. This is what the above
  <code>buildfile</code> will look like if <code>libhello</code> were a
  separate project:</p>

  <pre>import libs = libhello%lib{hello}

exe{hello}: {hxx cxx}{**} $libs</pre>

  <p>The <code>import</code> directive is a kind of variable assignment that
  resolves a <i>project-qualified</i> relative target
  (<code>libhello%lib{hello}</code>) to an unqualified absolute target and
  stores it in the variable (<code>libs</code> in our case). We can then
  expand the variable (<code>$libs</code>), normally in the dependency
  declaration, to get the imported target.</p>

  <p>If we needed to import several libraries, then we simply repeat the
  <code>import</code> directive, usually accumulating the result in the same
  variable, for example:</p>

  <pre>import libs  = libformat%lib{format}
import libs += libprint%lib{print}
import libs += libhello%lib{hello}

exe{hello}: {hxx cxx}{**} $libs</pre>

  <p>Let's now try to build our <code>hello</code> project that uses imported
  <code>libhello</code>:</p>

  <pre>$ b hello/
error: unable to import target libhello%lib{hello}
  info: use config.import.libhello command line variable to specify
        its project out_root</pre>

  <p>While that didn't work out well, it does make sense: the build system
  cannot know the location of <code>libhello</code> or which of its builds we
  want to use. Though it does helpfully suggest that we use
  <code>config.import.libhello</code> to specify its out directory
  (<code>out_root</code>). Let's point it to <code>libhello</code> source
  directory to use its in source build
  (<code>out_root&#160;==&#160;src_root</code>):</p>

  <pre>$ b hello/ config.import.libhello=libhello/
c++ libhello/libhello/cxx{hello} -> libhello/libhello/objs{hello}
ld libhello/libhello/libs{hello}
c++ hello/hello/cxx{hello} -> hello/hello/obje{hello}
ld hello/hello/exe{hello}</pre>

  <p>And it works. Naturally, the importation mechanism works the same for out
  of source builds and we can persist the <code>config.import.*</code>
  variables in the project's configuration. As an example, let's configure
  Clang builds of the two projects out of source:</p>

  <pre>$ b configure: libhello/@libhello-clang/ config.cxx=clang++
$ b configure: hello/@hello-clang/ config.cxx=clang++ \
  config.import.libhello=libhello-clang/

$ b hello-clang/
c++ libhello/libhello/cxx{hello} -> libhello-clang/libhello/objs{hello}
ld libhello-clang/libhello/libs{hello}
c++ hello/hello/cxx{hello} -> hello-clang/hello/obje{hello}
ld hello-clang/hello/exe{hello}</pre>

  <p>If the corresponding <code>config.import.*</code> variable is not
  specified, <code>import</code> searches for a project in a couple of other
  places. First, it looks in the list of subprojects starting from the
  importing project itself and then continuing with its outer amalgamations
  and their subprojects (see <a href="#intro-subproj">Subprojects and
  Amalgamations</a> for details on this subject).</p>

  <div class="note">
  <p>We've actually seen an example of this search step in action: the
  <code>tests</code> subproject in <code>libhello</code>. The test imports
  <code>libhello</code> which is automatically found as an amalgamation
  containing this subproject.</p>
  </div>

  <div class="note">
  <p>To skip searching in subprojects/amalgamations and proceed directly to
  the rule-specific search (described below), specify the
  <code>config.import.*</code> variable with an empty value. For example:</p>

  <pre>$ b configure: ... config.import.libhello=</pre>
  </div>

  <p>If the project being imported cannot be located using any of these
  methods, then <code>import</code> falls back to the rule-specific search.
  That is, a rule that matches the target may provide support for importing
  certain target types based on rule-specific knowledge. Support for importing
  installed libraries by the C++ link rule is a good example of this.
  Internally, the <code>cxx</code> module extracts the compiler's library
  search paths (that is, paths that would be used to resolve
  <code>-lfoo</code>) and then the link rule uses them to search for installed
  libraries. This allows us to use the same <code>import</code> directive
  regardless of whether we import a library from a separate build, from a
  subproject, or from an installation directory.</p>

  <div class="note">
  <p>Importation of an installed library will work even if it is not a
  <code>build2</code> project. Besides finding the library itself, the link
  rule will also try to locate its <code>pkg-config(1)</code> file and, if
  present, extract additional compile/link flags from it (see <a
  href="#cc-import-installed">Importation of Installed Libraries</a> for
  details). The link rule also automatically produces
  <code>pkg-config(1)</code> files for libraries that it installs.</p>
  </div>

  <div class="note">
  <p>A common problem with importing and using third-party C/C++ libraries is
  compiler warnings. Specifically, we are likely to include their headers into
  our project's source files which means we may see warnings in such headers
  (which we cannot always fix) mixed with warnings in our code (which we
  should normally be able to fix). See <a
  href="#cc-internal-scope">Compilation Internal Scope</a> for a mechanism to
  deal with this problem.</p>
  </div>

  <p>Let's now examine the exporting side of the importation mechanism. While
  a project doesn't need to do anything special to be found by
  <code>import</code>, it does need to handle locating the exported target (or
  targets; there could be several) within the project as well as loading their
  <code>buildfiles</code>. And this is the job of an <i>export stub</i>, the
  <code>build/export.build</code> file that you might have noticed in the
  <code>libhello</code> project:</p>

  <pre>libhello
├── build/
│   └── export.build
└── ...</pre>

  <p>Let's take a look inside:</p>

  <pre>$out_root/
{
  include libhello/
}

export $out_root/libhello/$import.target</pre>

  <p>An export stub is a special kind of <code>buildfile</code> that bridges
  from the importing project into exporting. It is loaded in a special
  temporary scope outside of any project, in a "no man's land" so to speak.
  The only variables set on the temporary scope are <code>src_root</code> and
  <code>out_root</code> of the project being imported as well as
  <code>import.target</code> containing the name of the target being imported
  (without project qualification; that is, <code>lib{hello}</code> in our
  example).</p>

  <p>Typically, an export stub will open the scope of the exporting project,
  load the <code>buildfile</code> that defines the target being exported and
  finally "return" the absolute target name to the importing project using the
  <code>export</code> directive. And this is exactly what the export stub in
  our <code>libhello</code> does.</p>

  <p>We now have all the pieces of the importation puzzle in place and you can
  probably see how they all fit together. To summarize, when the build system
  sees the <code>import</code> directive, it looks for a project with the
  specified name. If found, it creates a temporary scope, sets the
  <code>src/out_root</code> variables to point to the project and
  <code>import.target</code> &#8211; to the target name specified in the
  <code>import</code> directive. And then it load the project's export stub in
  this scope. Inside the export stub we switch to the project's root scope,
  load its <code>buildfile</code> and then use the <code>export</code>
  directive to return the exported target. Once the export stub is processed,
  the build system obtains the exported target and assigns it to the variable
  specified in the <code>import</code> directive.</p>

  <div class="note">
  <p>Our export stub is quite "loose" in that it allows importing any target
  defined in the project's source subdirectory <code>buildfile</code>. While
  we found it to be a good balance between strictness and flexibility, if you
  would like to "tighten" your export stubs, you can. For example:</p>

  <pre>if ($import.target == lib{hello})
  export $out_root/libhello/$import.target</pre>

  <p>If no <code>export</code> directive is executed in an export stub then
  the build system assumes that the target is not exported by the project and
  issues appropriate diagnostics.</p>
  </div>

  <p>Let's revisit the executable <code>buildfile</code> with which we started
  this section. Recall that it is for an executable that depends on a library
  which resides in the same project:</p>

  <pre>include ../libhello/ # Include lib{hello}.

exe{hello}: {hxx cxx}{**} ../libhello/lib{hello}</pre>

  <p>If <code>lib{hello}</code> is exported by this project, then instead of
  manually including its <code>buildfile</code> we can use <i>project-local
  importation</i>:</p>

  <pre>import lib = lib{hello}

exe{hello}: {hxx cxx}{**} $lib</pre>

  <p>The main advantage of project-local importation over inclusion is the
  ability to move things around without having to adjust locations in multiple
  places (the only place we need to do it is the export stub). This advantage
  becomes noticeable in more complex projects with a large number of
  components.</p>

  <div class="note">
  <p>An import is project-local if the target being imported has no project
  name. Note that the target must still be exported in the project's export
  stub. In other words, project-local importation use the same mechanism as
  the normal import.</p>
  </div>

  <p>Another special type of importation is <i>ad hoc importation</i>. It is
  triggered if the target being imported has no project name and is either
  absolute or is a relative directory (in which case it is interpreted as
  relative to the importing scope). Semantically this is similar a normal
  import but with the location of the project being imported hard-coded into
  the <code>buildfile</code>. While this would be a bad idea in most case,
  sometimes we may want to create a special <i>glue <code>buildfile</code></i>
  that "pulls" together several projects, usually for convenience of
  development.</p>

  <p>One typical case that calls for such a glue <code>buildfile</code> is a
  multi-package project. For example, we may have a <code>hello</code> project
  (in a more general sense, as in a version control repository) that contains
  the <code>libhello</code> library and <code>hello</code> executable packages
  (which are independent build system projects):</p>

  <pre>hello/
├── .git/
├── hello/
│   ├── build/
│   │   └── ...
│   ├── hello/
│   │   └── ...
│   ├── buildfile
│   └── manifest
└── libhello/
    ├── build/
    │   └── ...
    ├── libhello/
    │   └── ...
    ├── buildfile
    └── manifest</pre>

  <p>Notice that the root of this repository is not a build system project and
  we cannot, for example, just run the build system driver without any
  arguments to update all the packages. Instead we have to list them
  explicitly:</p>

  <pre>$ b hello/ libhello/</pre>

  <p>And that's inconvenient. To overcome this shortcoming we can turn the
  repository root into a simple build system project by adding a glue
  <code>buildfile</code> that imports (using ad hoc importation) and builds
  all the packages:</p>

  <pre>import pkgs = */

./: $pkgs</pre>

  <div class="note">
  <p>Unlike other import types, ad hoc importation does not rely (or require)
  an export stub. Instead, it directly loads a <code>buildfile</code> that
  could plausibly declare the target being imported.</p>

  <p>In the unlikely event of a project-local importation of a directory
  target, it will have to be spelled with an explicit <code>dir{}</code>
  target type, for example:</p>

  <pre>import d = dir{tests/}</pre>
  </div>

  <h2 id="intro-lib">1.6 Library Exportation and Versioning</h2>

  <p>By now we have examined and explained every line of every
  <code>buildfile</code> in our <code>hello</code> executable project. There
  are, however, still a few lines to be covered in the source subdirectory
  <code>buildfile</code> in <code>libhello</code>. Here it is in its
  entirety:</p>

  <pre>intf_libs = # Interface dependencies.
impl_libs = # Implementation dependencies.

lib{hello}: {hxx ixx txx cxx}{** -version} hxx{version} \
  $impl_libs $intf_libs

hxx{version}: in{version} $src_root/manifest

# Build options.
#
cxx.poptions =+ "-I$out_root" "-I$src_root"

obja{*}: cxx.poptions += -DLIBHELLO_STATIC_BUILD
objs{*}: cxx.poptions += -DLIBHELLO_SHARED_BUILD

# Export options.
#
lib{hello}:
{
  cxx.export.poptions = "-I$out_root" "-I$src_root"
  cxx.export.libs = $intf_libs
}

liba{hello}: cxx.export.poptions += -DLIBHELLO_STATIC
libs{hello}: cxx.export.poptions += -DLIBHELLO_SHARED

# For pre-releases use the complete version to make sure they cannot
# be used in place of another pre-release or the final version. See
# the version module for details on the version.* variable values.
#
if $version.pre_release
  lib{hello}: bin.lib.version = "-$version.project_id"
else
  lib{hello}: bin.lib.version = "-$version.major.$version.minor"

# Install into the libhello/ subdirectory of, say, /usr/include/
# recreating subdirectories.
#
{hxx ixx txx}{*}:
{
  install         = include/libhello/
  install.subdirs = true
}</pre>

  <p>Let's start with all those <code>cxx.export.*</code> variables. It turns
  out that merely exporting a library target is not enough for the importers
  of the library to be able to use it. They also need to know where to find
  its headers, which other libraries to link, etc. This information is carried
  in a set of target-specific <code>cxx.export.*</code> variables that
  parallel the <code>cxx.*</code> set and that together with the library's
  prerequisites constitute the <i>library metadata protocol</i>. Every time a
  source file that depends on a library is compiled or a binary is linked,
  this information is automatically extracted by the compile and link rules
  from the library dependency chain, recursively. And when the library is
  installed, this information is carried over to its
  <code>pkg-config(1)</code> file.</p>

  <div class="note">
  <p>Similar to the <code>c.*</code> and <code>cc.*</code> sets discussed
  earlier, there are also <code>c.export.*</code> and <code>cc.export.*</code>
  sets.</p>

  <p>Note, however, that there is no <code>*.export.coptions</code> since a
  library imposing compilation options on its consumers is bad practice (too
  coarse-grained, does not compose, etc). Instead, the recommended approach is
  to specify in the library documentation that it expects its consumers to use
  a certain compilation option. And if your library is unusable without
  exporting a compilation option and you are sure benefits outweigh the
  drawbacks, then you can specify it as part of <code>*.export.poptions</code>
  (it is still a good idea to prominently document this).</p>
  </div>

  <p>Here are the parts relevant to the library metadata protocol in the above
  <code>buildfile</code>:</p>

  <pre>intf_libs = # Interface dependencies.
impl_libs = # Implementation dependencies.

lib{hello}: ... $impl_libs $intf_libs

lib{hello}:
{
  cxx.export.poptions = "-I$out_root" "-I$src_root"
  cxx.export.libs = $intf_libs
}

liba{hello}: cxx.export.poptions += -DLIBHELLO_STATIC
libs{hello}: cxx.export.poptions += -DLIBHELLO_SHARED</pre>

  <p>As a first step we classify all our library dependencies into
  <i>interface dependencies</i> and <i>implementation dependencies</i>. A
  library is an interface dependency if it is referenced from our interface,
  for example, by including (importing) one of its headers (modules) from one
  of our (public) headers (modules) or if one of its functions is called from
  our inline or template functions. Otherwise, it is an implementation
  dependency.</p>

  <p>To illustrate the distinction between interface and implementation
  dependencies, let's say we've reimplemented our <code>libhello</code> to use
  <code>libformat</code> to format the greeting and <code>libprint</code> to
  print it.  Here is our new header (<code>hello.hxx</code>):</p>

  <pre>#include &lt;libformat/format.hxx>

namespace hello
{
  void
  say_hello_formatted (std::ostream&amp;, const std::string&amp; hello);

  inline void
  say_hello (std::ostream&amp; o, const std::string&amp; name)
  {
    say_hello_formatted (o, format::format_hello ("Hello", name));
  }
}</pre>

  <p>And this is the new source file (<code>hello.cxx</code>):</p>

  <pre>#include &lt;libprint/print.hxx>

namespace hello
{
  void
  say_hello_formatted (ostream&amp; o, const string&amp; h)
  {
    print::print_hello (o, h);
  }
}</pre>

  <p>In this case, <code>libformat</code> is our interface dependency since we
  both include its header in our interface and call it from one of our inline
  functions. In contrast, <code>libprint</code> is only included and used in
  the source file and so we can safely treat it as an implementation
  dependency. The corresponding <code>import</code> directives in our
  <code>buildfile</code> will therefore look like this:</p>

  <pre>import intf_libs = libformat%lib{format}
import impl_libs = libprint%lib{print}</pre>

  <p>The preprocessor options (<code>poptions</code>) of an interface
  dependency must be made available to our library's users. The library itself
  should also be explicitly linked whenever our library is linked. All this is
  achieved by listing the interface dependencies in the
  <code>cxx.export.libs</code> variable:</p>

  <pre>lib{hello}:
{
  cxx.export.libs = $intf_libs
}</pre>

  <div class="note">
  <p>More precisely, the interface dependency should be explicitly linked if a
  user of our library may end up with a direct call to the dependency in one
  of their object files. Not linking such a library is called
  <i>underlinking</i> while linking a library unnecessarily (which can happen
  because we've included its header but are not actually calling any of its
  non-inline/template functions) is called <i>overlinking</i>. Underlinking is
  an error on some platforms while overlinking may slow down the process
  startup and/or waste its memory.</p>

  <p>Note also that this only applies to shared libraries. In case of static
  libraries, both interface and implementation dependencies are always linked,
  recursively. Specifically, when linking a shared library, only libraries
  specified in its <code>*.export.libs</code> are linked. While when linking a
  static library, all its library prerequisites as well as those specified in
  <code>*.libs</code> are linked. Note that <code>*.export.libs</code> is not
  used when linking a static library since it is naturally assumed that all
  such libraries are also specified as library prerequisites or in
  <code>*.libs</code>.</p>
  </div>

  <p>The remaining lines in the library metadata fragment are:</p>

  <pre>lib{hello}:
{
  cxx.export.poptions = "-I$out_root" "-I$src_root"
}

liba{hello}: cxx.export.poptions += -DLIBHELLO_STATIC
libs{hello}: cxx.export.poptions += -DLIBHELLO_SHARED</pre>

  <p>The first line makes sure the users of our library can locate its headers
  by exporting the relevant <code>-I</code> options. The last two lines define
  the library type macros that are relied upon by the <code>export.hxx</code>
  header to properly setup symbol exporting.</p>

  <div class="note">
  <p>The <code>liba{}</code> and <code>libs{}</code> target types correspond
  to the static and shared libraries, respectively. And <code>lib{}</code> is
  actually a target group that can contain one, the other, or both as its
  members.</p>

  <p>Specifically, when we build a <code>lib{}</code> target, which members
  will be built is determined by the <code>config.bin.lib</code> variable with
  the <code>static</code>, <code>shared</code>, and <code>both</code>
  (default) possible values. So to only build a shared library we can run:</p>

  <pre>$ b config.bin.lib=shared</pre>

  <p>When it comes to linking <code>lib{}</code> prerequisites, which member
  is picked is controlled by the <code>config.bin.{exe,liba,libs}.lib</code>
  variables for the executable, static library, and shared library targets,
  respectively. Each contains a list of <code>shared</code> and
  <code>static</code> values that determine the linking preferences. For
  example, to build both shared and static libraries but to link executable to
  static libraries we can run:</p>

  <pre>$ b config.bin.lib=both config.bin.exe.lib=static</pre>

  <p>See the <a href="#module-bin"><code>bin</code></a> module documentation
  for more information.</p>
  </div>

  <p>Note also that we don't need to change anything in the above
  <code>buildfile</code> if our library is header-only. In <code>build2</code>
  this is handled dynamically and automatically based on the absence of source
  file prerequisites. In fact, the same library can be header-only on some
  platforms or in some configuration and "source-ful" in others.</p>

  <div class="note">
  <p>In <code>build2</code> a header-only library (or a module interface-only
  library) is not a different kind of library compared to static/shared
  libraries but is rather a binary-less, or <i>binless</i> for short, static
  or shared library. So, theoretically, it is possible to have a library that
  has a binless static and a binary-ful (<i>binful</i>) shared variants. Note
  also that binless libraries can depend on binful libraries and are fully
  supported where the <code>pkg-config(1)</code> functionality is
  concerned.</p>

  <p>One counter-intuitive aspect of having a binless library that depends on
  a system binful library, for example, <code>-lm</code>, is that you still
  have to specify the system library in both <code>*.export.libs</code> and
  <code>*.libs</code> because the latter is used when linking the static
  variant of the binless library. For example:</p>

  <pre>cxx.libs = -lm
lib{hello}: cxx.export.libs = -lm</pre>

  <p>If you are creating a new library with <a
  href="../../bdep/doc/bdep-new.xhtml"><code><b>bdep-new(1)</b></code></a> and
  are certain that it will always be binless and in all configurations, then
  you can produce a simplified <code>buildfile</code> by specifying the
  <code>binless</code> option, for example:</p>

  <pre>$ bdep new -l c++ -t lib,binless libheader-only</pre>
  </div>

  <p>Let's now turn to the second subject of this section and the last
  unexplained bit in our <code>buildfile</code>: shared library versioning.
  Here is the relevant fragment:</p>

  <pre>if $version.pre_release
  lib{hello}: bin.lib.version = "-$version.project_id"
else
  lib{hello}: bin.lib.version = "-$version.major.$version.minor"</pre>

  <p>Shared library versioning is a murky, platform-specific area. Instead of
  trying to come up with a unified versioning scheme that few are likely to
  comprehend (similar to <code>autoconf</code>), <code>build2</code> provides
  a platform-independent versioning scheme as well as the ability to specify
  platform-specific versions in a native format.</p>

  <p>The library version is specified with the <code>bin.lib.version</code>
  target-specific variable. Its value should be a sequence of
  <code>@</code>-pairs with the left hand side (key) being the platform name
  and the right hand side (value) being the version. An empty key (in which
  case <code>@</code> can be omitted) signifies the platform-independent
  version (see the <a href="#module-bin"><code>bin</code></a> module
  documentation for the exact semantics). For example:</p>

  <pre>lib{hello}: bin.lib.version = -1.2 linux@3</pre>

  <p><span class="note">While the interface for platform-specific versions is
  defined, their support is currently only implemented on Linux.</span></p>

  <p>A platform-independent version is embedded as a suffix into the library
  name (and into its <code>soname</code> on relevant platforms) while
  platform-specific versions are handled according to the platform. Continuing
  with the above example, these would be the resulting shared library names on
  select platforms:</p>

  <pre>libhello.so.3       # Linux
libhello-1.2.dll    # Windows
libhello-1.2.dylib  # Mac OS</pre>

  <p>With this background we can now explain what's going in our
  <code>buildfile</code>:</p>

  <pre>if $version.pre_release
  lib{hello}: bin.lib.version = "-$version.project_id"
else
  lib{hello}: bin.lib.version = "-$version.major.$version.minor"</pre>

  <p>Here we only use platform-independent library versioning. For releases we
  embed both major and minor version components assuming that patch releases
  are binary compatible. For pre-releases, however, we use the complete
  version to make sure it cannot be used in place of another pre-release or
  the final version.</p>

  <div class="note">
  <p>The <code>version.project_id</code> variable contains the project's (as
  opposed to package's), shortest "version id". See the <a
  href="#module-version"><code>version</code></a> module documentation for
  details.</p>
  </div>

  <h2 id="intro-subproj">1.7 Subprojects and Amalgamations</h2>

  <p>In <code>build2</code> projects can contain other projects, recursively.
  In this arrangement the outer project is called an <i>amalgamation</i> and
  the inner &#8211; <i>subprojects</i>. In contrast to importation where we
  merely reference a project somewhere else, amalgamation is physical
  containment. It can be <i>strong</i> where the src directory of a subproject
  is within the amalgamating project or <i>weak</i> where only the out
  directory is contained.</p>

  <p>There are several distinct use cases for amalgamations. We've already
  discussed the <code>tests/</code> subproject in <code>libhello</code>. To
  recap: traditionally, it is made a subproject rather than a subdirectory to
  support building it as a standalone project in order to test library
  installations.</p>

  <p>As discussed in <a href="#intro-import">Target Importation</a>,
  subprojects and amalgamations (as well as their subprojects, recursively)
  are automatically considered when resolving imports. As a result,
  amalgamation can be used to <i>bundle</i> dependencies to produce an
  external dependency-free distribution. For example, if our
  <code>hello</code> project imports <code>libhello</code>, then we could copy
  the <code>libhello</code> project into <code>hello</code>, for example:</p>

  <pre>$ tree hello/
hello/
├── build/
│   └── ...
├── hello/
│   ├── hello.cxx
│   └── ...
├── libhello/
│   ├── build/
│   │   └── ...
│   ├── libhello/
│   │   ├── hello.hxx
│   │   ├── hello.cxx
│   │   └── ...
│   ├── tests/
│   │   └── ...
│   └── buildfile
└── buildfile

$ b hello/
c++ hello/libhello/libhello/cxx{hello} ->
    hello/libhello/libhello/objs{hello}
ld hello/libhello/libhello/libs{hello}
c++ hello/hello/cxx{hello} -> hello/hello/obje{hello}
ld hello/hello/exe{hello}</pre>

  <p>Note, however, that while project bundling can be useful in certain
  cases, it does not scale as a general dependency management solution. For
  that, independent packaging and proper dependency management are the
  appropriate mechanisms.</p>

  <div class="note">
  <p>By default <code>build2</code> looks for subprojects only in the root
  directory of a project. That is, every root subdirectory is examined to see
  if it itself is a project root. If you need to place a subproject somewhere
  else in your project's directory hierarchy, then you will need to specify
  its location (and of all other subprojects) explicitly with the
  <code>subprojects</code> variable in <code>bootstrap.build</code>. For
  example, if above we placed <code>libhello</code> into the
  <code>extras/</code> subdirectory of <code>hello</code>, then our
  <code>bootstrap.build</code> would need to start like this:</p>

  <pre>project = hello
subprojects = extras/libhello/
...</pre>

  <p>Note also that while importation of specific targets from subprojects is
  always performed, whether they are loaded and built as part of the overall
  project build is controlled using the standard subdirectories inclusion and
  dependency mechanisms. Continuing with the above example, if we adjust the
  root <code>buildfile</code> in <code>hello</code> to exclude the
  <code>extras/</code> subdirectory from the build:</p>

  <pre>./: {*/ -build/ -extras/}</pre>

  <p>Then while we can still import <code>libhello</code> from any
  <code>buildfile</code> in our project, the entire <code>libhello</code> (for
  example, its tests) will never be built as part of the <code>hello</code>
  build.</p>

  <p>Similar to subprojects we can also explicitly specify the project's
  amalgamation with the <code>amalgamation</code> variable (again, in
  <code>bootstrap.build</code>). This is rarely necessary except if you want
  to prevent the project from being amalgamated, in which case you should set
  it to the empty value.</p>

  <p>If either of these variables is not explicitly set, then they will
  contain the automatically discovered values.</p>
  </div>

  <p>Besides affecting importation, another central property of amalgamation
  is configuration inheritance. As an example, let's configure the above
  bundled <code>hello</code> project in its src directory:</p>

  <pre>$ b configure: hello/ config.cxx=clang++ config.cxx.coptions=-g

$ tree
hello/
├── build/
│   ├── config.build
│   └── ...
├── libhello/
│   ├── build/
│   │   ├── config.build
│   │   └── ...
│   └── ...
└── ...</pre>

  <p>As you can see, we now have the <code>config.build</code> files in both
  projects' <code>build/</code> subdirectories. If we examine the
  amalgamation's <code>config.build</code>, we will see the familiar
  picture:</p>

  <pre>$ cat hello/build/config.build

config.cxx = clang++
config.cxx.poptions = [null]
config.cxx.coptions = -g
config.cxx.loptions = [null]
config.cxx.aoptions = [null]
config.cxx.libs = [null]

...
</pre>

  <p>The subproject's <code>config.build</code>, however, is pretty much
  empty:</p>

  <pre>$ cat hello/libhello/build/config.build

# Base configuration inherited from ../</pre>

  <p>As the comment suggests, the base configuration is inherited from the
  outer project. We can, however, override some values if we need to. For
  example (note that we are re-configuring the <code>libhello</code>
  subproject):</p>

  <pre>$ b configure: hello/libhello/ config.cxx.coptions=-O2

$ cat hello/libhello/build/config.build

# Base configuration inherited from ../

config.cxx.coptions = -O2</pre>

  <p>This configuration inheritance combined with import resolution is behind
  the most common use of amalgamations in <code>build2</code> &#8211; shared
  build configurations. Let's say we are developing multiple projects, for
  example, <code>hello</code> and <code>libhello</code> that it imports:</p>

  <pre>$ ls -1
hello/
libhello/</pre>

  <p>And we want to build them with several compilers, let's say GCC and
  Clang. As we have already seen in <a
  href="#intro-operations-config">Configuring</a>, we can configure several
  out of source builds for each compiler, for example:</p>

  <pre>$ b configure: libhello/@libhello-gcc/   config.cxx=g++
$ b configure: libhello/@libhello-clang/ config.cxx=clang++

$ b configure: hello/@hello-gcc/   \
               config.cxx=g++      \
               config.import.libhello=libhello-gcc/
$ b configure: hello/@hello-clang/ \
               config.cxx=clang++  \
               config.import.libhello=libhello-clang/

$ ls -l
hello/
hello-gcc/
hello-clang/
libhello/
libhello-gcc/
libhello-clang/</pre>

  <p>Needless to say, this is a lot of repetitive typing. Another problem is
  future changes to the configurations. If, for example, we need to adjust
  compile options in the GCC configuration, then we will have to (remember to)
  do it in both places.</p>

  <p>You can probably sense where this is going: why not create two shared
  build configurations (that is, amalgamations), one for GCC and one for
  Clang, within each of which we build both of our projects (as their
  subprojects)? This is how we can do that:</p>

  <pre>$ b create: build-gcc/,cc   config.cxx=g++
$ b create: build-clang/,cc config.cxx=clang++

$ b configure: libhello/@build-gcc/libhello/
$ b configure: hello/@build-gcc/hello/

$ b configure: libhello/@build-clang/libhello/
$ b configure: hello/@build-clang/hello/

$ ls -l
hello/
libhello/
build-gcc/
build-clang/</pre>

  <p>Let's explain what's going on here. First, we create two build
  configurations using the <code>create</code> meta-operation. These are real
  <code>build2</code> projects just tailored for housing other projects as
  subprojects. In <code>create</code>, after the directory name, we specify
  the list of modules to load in the project's <code>root.build</code>. In our
  case we specify <code>cc</code> which is a common module for C-based
  languages (see <a href="b.xhtml"><code><b>b(1)</b></code></a> for details on
  <code>create</code> and its parameters).</p>

  <div class="note">
  <p>When creating build configurations it is a good idea to get into the
  habit of using the <code>cc</code> module instead of <code>c</code> or
  <code>cxx</code> since with more complex dependency chains we may not know
  whether every project we build only uses C or C++. In fact, it is not
  uncommon for a C++ project to have C implementation details and even the
  other way around (yes, really, there are C libraries with C++
  implementations).</p>
  </div>

  <p>Once the configurations are ready we simply configure our
  <code>libhello</code> and <code>hello</code> as subprojects in each of them.
  Note that now we neither need to specify <code>config.cxx</code>, because it
  will be inherited from the amalgamation, nor <code>config.import.*</code>,
  because the import will be automatically resolved to a subproject.</p>

  <p>Now, to build a specific project in a particular configuration we simply
  build the corresponding subdirectory. We can also build the entire build
  configuration if we want to. For example:</p>

  <pre>$ b build-gcc/hello/

$ b build-clang/</pre>

  <div class="note">
  <p>In case you've already looked into <a
  href="../../bpkg/doc/bpkg.xhtml"><code><b>bpkg(1)</b></code></a> and/or <a
  href="../../bdep/doc/bdep.xhtml"><code><b>bdep(1)</b></code></a>, their
  build configurations are actually these same amalgamations (created
  underneath with the <code>create</code> meta-operation) and their packages
  are just subprojects. And with this understanding you are free to interact
  with them directly using the build system interface.</p>
  </div>

  <h2 id="intro-lang">1.8 Buildfile Language</h2>

  <p>By now we should have a good overall sense of what writing
  <code>buildfiles</code> feels like. In this section we will examine the
  language in slightly more detail and with more precision.</p>

  <p>Buildfile is primarily a declarative language with support for variables,
  pure functions, repetition (<code>for</code>-loop), conditional
  inclusion/exclusion (<code>if-else</code>), and pattern matching
  (<code>switch</code>). At the lexical level, <code>buildfiles</code> are
  UTF-8 encoded text restricted to the Unicode graphic characters, tabs
  (<code>\t</code>), carriage returns (<code>\r</code>), and line feeds
  (<code>\n</code>).</p>

  <p>Buildfile is a line-oriented language. That is, every construct ends at
  the end of the line unless escaped with line continuation (trailing
  <code>\</code>). For example:</p>

  <pre>exe{hello}: {hxx cxx}{**} \
  $libs</pre>

  <p>Some lines may start a <i>block</i> if followed by <code>{</code> on the
  next line. Such a block ends with a closing <code>}</code> on a separate
  line. Some types of blocks can nest. For example:</p>

  <pre>if ($cxx.target.class == 'windows')
{
  if ($cxx.target.system == 'ming32')
  {
    ...
  }
}</pre>

  <p>A comment starts with <code>#</code> and everything from this character
  and until the end of the line is ignored. A multi-line comment starts with
  <code>#\</code> on a separate line and ends with the same character
  sequence, again on a separate line. For example:</p>

  <pre># Single line comment.

info 'Hello, World!' # Trailing comment.

#\
Multi-
line
comment.
#\</pre>

  <p>The three primary Buildfile constructs are dependency declaration,
  directive, and variable assignment. We've already used all three but let's
  see another example:</p>

  <pre>include ../libhello/                              # Directive.

exe{hello}: {hxx cxx}{**} ../libhello/lib{hello}  # Dependency.

cxx.poptions += -DNDEBUG                          # Variable.</pre>

  <p>There is also the scope opening (we've seen one in
  <code>export.build</code>) as well as target-specific and
  prerequisite-specific variable assignment blocks. The latter two are used to
  assign several entity-specific variables at once. For example:</p>

  <pre>details/                          # Scope.
{
  hxx{*}: install = false
}

lib{hello}:                       # Target-specific.
{
  cxx.export.poptions = "-I$src_root"
  cxx.export.libs = $intf_libs
}

exe{test}: file{test.roundtrip}:  # Prerequisite-specific.
{
  test.stdin  = true
  test.stdout = true
}</pre>

  <p>Variable assignment blocks can be combined with dependency declarations,
  for example:</p>

  <pre>h{config}: in{config}
{
  in.symbol = '@'
  in.mode = lax

  SYSTEM_NAME = $c.target.system
  SYSTEM_PROCESSOR = $c.target.cpu
}</pre>

  <p>In case of a dependency chain, if the chain ends with a colon
  (<code>:</code>), then the block applies to the last set of prerequisites.
  Otherwise, it applies to the last set of targets. For example:</p>

  <pre>./: exe{test}: cxx{main}
{
  test = true        # Applies to the exe{test} target.
}

./: exe{test}: libue{test}:
{
  bin.whole = false  # Applies to the libue{test} prerequisite.
}</pre>

  <div class="note">
  <p>All prerequisite-specific variables must be assigned at once as part of
  the dependency declaration since repeating the same dependency again
  duplicates the prerequisite rather than references the already existing
  one.</p>
  </div>

  <p>There is also the target type/pattern-specific variable assignment block,
  for example:</p>

  <pre>exe{*.test}:
{
  test = true
  install = false
}</pre>

  <p>See <a href="#variables">Variables</a> for a more detailed discussion of
  variables.</p>

  <p>Each <code>buildfile</code> is processed linearly with directives
  executed and variables expanded as they are encountered. However, certain
  variables, for example <code>cxx.poptions</code>, are also expanded by rules
  during execution in which case they will "see" the final value set in the
  <code>buildfile</code>.</p>

  <div class="note">
  <p>Unlike GNU <code>make(1)</code>, which has deferred (<code>=</code>) and
  immediate (<code>:=</code>) variable assignments, all assignments in
  <code>build2</code> are immediate. For example:</p>

  <pre>x = x
y = $x
x = X
info $y # Prints 'x', not 'X'.</pre>
  </div>

  <h3 id="intro-lang-expand">1.8.1 Expansion and Quoting</h3>

  <p>While we've discussed variable expansion and lookup earlier, to recap, to
  get the variable's value we use <code>$</code> followed by its name. The
  variable name is first looked up in the current scope (that is, the scope in
  which the expansion was encountered) and, if not found, in the outer scopes,
  recursively.</p>

  <p>There are two other kinds of expansions: function calls and evaluation
  contexts, or <i>eval contexts</i> for short. Let's start with the latter
  since function calls are built on top of eval contexts.</p>

  <p>An eval context is essentially a fragment of a line with additional
  interpretations of certain characters to support value comparison, logical
  operators, and a few other constructs. Eval contexts begin with
  <code>(</code>, end with <code>)</code>, and can nest. Here are a few
  examples:</p>

  <pre>info ($src_root != $out_root)                 # Prints true or false.
info ($src_root == $out_root ? 'in' : 'out')  # Prints in or out.

macos = ($cxx.target.class == 'macos')  # Assigns true or false.
linux = ($cxx.target.class == 'linux')  # Assigns true or false.

if ($macos || $linux)  # Also eval context.
  ...</pre>

  <div class="note">
  <p>Below is the eval context grammar that shows supported operators and
  their precedence.</p>

  <pre>eval:         '(' (eval-comma | eval-qual)? ')'
eval-comma:   eval-ternary (',' eval-ternary)*
eval-ternary: eval-or ('?' eval-ternary ':' eval-ternary)?
eval-or:      eval-and ('||' eval-and)*
eval-and:     eval-comp ('&amp;&amp;' eval-comp)*
eval-comp:    eval-value (('=='|'!='|'&lt;'|'>'|'&lt;='|'>=') eval-value)*
eval-value:   value-attributes? (&lt;value> | eval | '!' eval-value)
eval-qual:    &lt;name> ':' &lt;name>

value-attributes: '[' &lt;key-value-pairs> ']'</pre>

  <p>Note that <code>?:</code> (ternary operator) and <code>!</code> (logical
  not) are right-associative. Unlike C++, all the comparison operators have
  the same precedence. A qualified name cannot be combined with any other
  operator (including ternary) unless enclosed in parentheses. The
  <code>eval</code> option in the <code>eval-value</code> production shall
  contain a single value only (no commas).</p>

  <p>Additionally, the <code>`</code> (backtick) and <code>|</code> (bitwise
  or) tokens are reserved for future support of arithmetic evaluation contexts
  and evaluation pipelines, respectively.</p>
  </div>

  <p>A function call starts with <code>$</code> followed by its name and an
  eval context listing its arguments. Note that there is no space between the
  name and <code>(</code>. For example:</p>

  <pre>x =
y = Y

info $empty($x)  # true
info $empty($y)  # false

if $regex.match($y, '[A-Z]')
  ...

p = $src_base/foo.txt

info $path.leaf($src_base)              # foo.txt
info $path.directory($src_base)         # $src_base
info $path.base($path.leaf($src_base))  # foo</pre>

  <p>Note that the majority of functions in <code>build2</code> are
  <i>pure</i> in a sense that they do not alter the build state in any way
  (see <a href="#functions">Functions</a> for details).</p>

  <div class="note">
  <p>Functions in <code>build2</code> are currently defined either by the
  build system core or build system modules and are implemented in C++. In the
  future it will be possible to define custom functions in
  <code>buildfiles</code> (also in C++).</p>
  </div>

  <p>Variable and function names follow the C identifier rules. We can also
  group variables into namespaces and functions into families by combining
  multiple identifiers with <code>.</code>. These rules are used to determine
  the end of the variable name in expansions. If, however, a name is
  recognized as being longer than desired, then we can use the eval context to
  explicitly specify its boundaries. For example:</p>

  <pre>base = foo
name = $(base).txt</pre>

  <p>What is the structure of a variable value? Consider this assignment:</p>

  <pre>x = foo bar</pre>

  <p>The value of <code>x</code> could be a string, a list of two strings, or
  something else entirely. In <code>build2</code> the fundamental, untyped
  value is a <i>list of names</i>. A value can be typed to something else
  later but it always starts as a list of names. So in the above example we
  have a list of two names, <code>foo</code> and <code>bar</code>, the same as
  in this example (notice the extra spaces):</p>

  <pre>x = foo    bar</pre>

  <div class="note">
  <p>The motivation behind going with a list of names instead of a string or a
  list of strings is that at its core we are dealing with targets and their
  prerequisites and it would be natural to make the representation of their
  names (that is, the way we refer to them) the default. Consider the
  following two examples; it would be natural for them to mean the same
  thing:</p>

  <pre>exe{hello}: {hxx cxx}{**}</pre>

  <pre>prereqs = {hxx cxx}{**}
exe{hello}: $prereqs</pre>

  <p>Note also that the name semantics was carefully tuned to be
  <i>reversible</i> to its syntactic representation for common non-name
  values, such as paths, command line options, etc., that are usually found in
  <code>buildfiles</code>.</p>
  </div>

  <p>To get to individual elements of a list, an expansion can be followed by
  a subscript. Note that subscripts are only recognize inside evaluation
  contexts and there should be no space between the expansion and
  <code>[</code>. For example:</p>

  <pre>x = foo bar

info ($x[0])                                # foo
info ($regex.split('foo bar', ' ', '')[1])  # bar</pre>

  <p>Names are split into a list at whitespace boundaries with certain other
  characters treated as syntax rather than as part of the value. Here are a
  few examples:</p>

  <pre>x = $y          # expansion
x = (a == b)    # eval context
x = {foo bar}   # name generation
x = [null]      # attributes
x = name@value  # pairs
x = # start of a comment</pre>

  <p>The complete set of syntax characters is <code>$(){}@#"'</code> plus
  space and tab, as well as <code>[]</code>, but only in certain contexts (see
  <a href="#attributes">Attributes</a> for details). If instead we need these
  characters to appear literally as part of the value, then we either have to
  <i>escape</i> or <i>quote</i> them.</p>

  <div class="note">
  <p>Additionally, <code>*?[</code> will be treated as wildcards in name
  patterns (see <a href="#name-patterns">Name Patterns</a> for details). Note
  that this treatment can only be inhibited with quoting and not escaping.</p>

  <p>While name patterns are recognized inside evaluation contexts, in certain
  cases the <code>?[</code> characters are treated as part of the ternary
  operator and value subscript, respectively. In such case, to be treat as
  wildcards rather than as syntax, these characters have to be escaped, for
  example:</p>

  <pre>x = (foo.\?xx)
y = ($foo\[123].txt)</pre>
  </div>

  <p>To escape a special character, we prefix it with a backslash
  (<code>\</code>; to specify a literal backslash, double it). For
  example:</p>

  <pre>x = \$
y = C:\\Program\ Files</pre>

  <p>Similar to UNIX shells, <code>build2</code> supports single
  (<code>''</code>) and double (<code>""</code>) quoting with roughly the same
  semantics. Specifically, expansions (variable, function call, and eval
  context) and escaping are performed inside double-quoted strings but not in
  single-quoted. Note also that quoted strings can span multiple lines with
  newlines treated literally (unless escaped in double-quoted strings). For
  example:</p>

  <pre>x = "(a != b)"  # true
y = '(a != b)'  # (a != b)

x = "C:\\Program Files"
y = 'C:\Program Files'

t = 'line one
line two
line three'</pre>

  <p>Since quote characters are also part of the syntax, if you need to
  specify them literally in the value, then they will either have to be
  escaped or quoted. For example:</p>

  <pre>cxx.poptions += -DOUTPUT='"debug"'
cxx.poptions += -DTARGET=\"$cxx.target\"</pre>

  <p>An expansion can be one of two kinds: <i>spliced</i> or
  <i>concatenated</i>. In a spliced expansion the variable, function, or eval
  context is separated from other text with whitespaces. In this case, as the
  name suggests, the resulting list of names is spliced into the value. For
  example:</p>

  <pre>x = 'foo fox'
y = bar $x baz  # Three names: 'bar' 'foo fox' 'baz'.</pre>

  <div class="note">
  <p>This is an important difference compared to the semantics of UNIX shells
  where the result of expansion is re-parsed. In particular, this is the
  reason why you won't see quoted expansions in <code>buildfiles</code> as
  often as in (well-written) shell scripts.</p>
  </div>

  <p>In a concatenated expansion the variable, function, or eval context are
  combined with unseparated text before and/or after the expansion. For
  example:</p>

  <pre>x = 'foo fox'
y = bar$(x)foz  # Single name: 'barfoo foxbaz'</pre>

  <p>A concatenated expansion is typed unless it is quoted. In a typed
  concatenated expansion the parts are combined in a type-aware manner while
  in an untyped &#8211; literally, as string. To illustrate the difference,
  consider this <code>buildfile</code> fragment:</p>

  <pre>info $src_root/foo.txt
info "$src_root/foo.txt"</pre>

  <p>If we run it on a UNIX-like operating system, we will see two identical
  lines, along these lines:</p>

  <pre>/tmp/test/foo.txt
/tmp/test/foo.txt</pre>

  <p>However, if we run it on Windows (which uses backslashes as directory
  separators), we will see the output along these lines:</p>

  <pre>C:\test\foo.txt
C:\test/foo.txt</pre>

  <p>The typed concatenation resulted in a native directory separator because
  <code>dir_path</code> (the <code>src_root</code> type) did the right
  thing.</p>

  <p>Not every typed concatenation is well defined and in certain situations
  we may need to force untyped concatenation with quoting. Options specifying
  header search paths (<code>-I</code>) are a typical case, for example:</p>

  <pre>cxx.poptions =+ "-I$out_root" "-I$src_root"</pre>

  <p>If we were to remove the quotes, we would see the following error:</p>

  <pre>buildfile:6:20: error: no typed concatenation of &lt;untyped> to dir_path
  info: use quoting to force untyped concatenation</pre>

  <h3 id="intro-if-else">1.8.2 Conditions (<code>if-else</code>)</h3>

  <p>The <code>if</code> directive can be used to conditionally exclude
  <code>buildfile</code> fragments from being processed. The conditional
  fragment can be a single (separate) line or a block with the initial
  <code>if</code> optionally followed by a number of <code>elif</code>
  directives and a final <code>else</code>, which together form the
  <code>if-else</code> chain. An <code>if-else</code> block can contain nested
  <code>if-else</code> chains. For example:</p>

  <pre>if ($cxx.target.class == 'linux')
  info 'linux'
elif ($cxx.target.class == 'windows')
{
  if ($cxx.target.system == 'mingw32')
    info 'windows-mingw'
  elif ($cxx.target.system == 'win32-msvc')
    info 'windows-msvc'
  else
    info 'windows-other'
}
else
  info 'other'</pre>

  <p>The <code>if</code> and <code>elif</code> directive names must be
  followed by an expression that expands to a single, literal
  <code>true</code> or <code>false</code>. This can be a variable expansion, a
  function call, an eval context, or a literal value. For example:</p>

  <pre>if $version.pre_release
  ...

if $regex.match($x, '[A-Z]')
  ...

if ($cxx.target.class == 'linux')
  ...

if false
{
  # disabled fragment
}

x = X
if $x  # Error, must expand to true or false.
  ...</pre>

  <p>There are also <code>if!</code> and <code>elif!</code> directives which
  negate the condition that follows (note that there is no space before
  <code>!</code>). For example:</p>

  <pre>if! $version.pre_release
  ...
elif! $regex.match($x, '[A-Z]')
  ...</pre>

  <p>Note also that there is no notion of variable locality in
  <code>if-else</code> blocks and any value set inside is visible outside. For
  example:</p>

  <pre>if true
{
  x = X
}

info $x  # Prints 'X'.</pre>

  <p>The <code>if-else</code> chains should not be used for conditional
  dependency declarations since this would violate the expectation that all of
  the project's source files are listed as prerequisites, irrespective of the
  configuration.  Instead, use the special <code>include</code>
  prerequisite-specific variable to conditionally include prerequisites into
  the build. For example:</p>

  <pre># Incorrect.
#
if ($cxx.target.class == 'linux')
  exe{hello}: cxx{hello-linux}
elif ($cxx.target.class == 'windows')
  exe{hello}: cxx{hello-win32}

# Correct.
#
exe{hello}: cxx{hello-linux}: include = ($cxx.target.class == 'linux')
exe{hello}: cxx{hello-win32}: include = ($cxx.target.class == 'windows')</pre>

  <h3 id="intro-switch">1.8.3 Pattern Matching (<code>switch</code>)</h3>

  <p>The <code>switch</code> directive is similar to <code>if-else</code> in
  that it allows us to conditionally exclude <code>buildfile</code> fragments
  from being processed. The difference is in the way the conditions are
  structured: while in <code>if-else</code> we can do arbitrary tests, in
  <code>switch</code> we match one or more values against a set of patterns.
  For instance, this is how we can reimplement the first example from <a
  href="#intro-if-else">Conditionals (<code>if-else</code>)</a> using
  <code>switch</code>:</p>

  <pre>switch $cxx.target.class, $cxx.target.system
{
  case 'linux'
    info 'linux'

  case 'windows', 'mingw32'
    info 'windows-mingw'

  case 'windows', 'win32-msvc'
    info 'windows-msvc'

  case 'windows'
    info 'windows-other'

  default
    info 'other'
}</pre>

  <p>Similar to <code>if-else</code>, the conditional fragment can be a single
  (separate) line or a block with a zero or more <code>case</code>
  lines/blocks optionally followed by <code>default</code>. A
  <code>case-default</code> block can contain nested <code>switch</code>
  directives (though it is often more convenient to use multiple values in a
  single <code>switch</code>, as shown above). For example:</p>

  <pre>switch $cxx.target.class
{
  ...
  case 'windows'
  {
    switch $cxx.target.system
    {
      case 'mingw32'
        info 'windows-mingw'

      case 'win32-msvc'
        info 'windows-msvc'

      default
        info 'windows-other'
    }
  }
  ...
}</pre>

  <p>All the <code>case</code> fragments are tried in the order specified with
  the first that matches evaluated and all the others ignored (that is, there
  is no explicit <code>break</code> nor the ability to fall through). If none
  of the <code>case</code> patterns matched and there is the
  <code>default</code> fragment, then it is evaluated. Multiple
  <code>case</code> lines can be specified for a single conditional fragment.
  For example:</p>

  <pre>switch $cxx.target.class, $cxx.id
{
  case 'windows', 'msvc'
  case 'windows', 'clang'
    info 'msvcrt'
}</pre>

  <p>The <code>switch</code> directive name must be followed by one or more
  <i>value expressions</i> separated with a comma (<code>,</code>). Similarly,
  the <code>case</code> directive name must be followed by one or more
  <i>pattern expressions</i> separated with a comma (<code>,</code>). These
  expressions can be variable expansions, function calls, eval contexts, or
  literal values.</p>

  <p>If multiple values/patterns are specified, then all the <code>case</code>
  patterns must match in order for the corresponding fragment to be evaluated.
  However, if some trailing patterns are omitted, then they are considered as
  matching. For example:</p>

  <pre>switch $cxx.target.class, $cxx.target.system
{
  case 'windows', 'mingw32'
    info 'windows-mingw'

  case 'windows', 'win32-msvc'
    info 'windows-msvc'

  case 'windows'
    info 'windows-other'
}</pre>

  <p>The first pattern in the pattern expression can be optionally followed by
  one or more alternative patterns separated by a vertical bar
  (<code>|</code>). Only one of the alternatives need to match in order for
  the whole pattern expression to be considered as matching. For example:</p>

  <pre>switch $cxx.id
{
  case 'clang' | 'clang-apple'
    ...
}</pre>

  <p>The value in the value expression can be optionally followed by a colon
  (<code>:</code>) and a <i>match function</i>. If the match function is not
  specified, then equality is used by default. For example:</p>

  <pre>switch $cxx.target.cpu: regex.match
{
  case 'i[3-6]86'
    ...

  case 'x86_64'
    ...
}</pre>

  <p>The match function name can be optionally followed by additional values
  that are passed as the third argument to the match function. This is
  normally used to specify additional match flags, for example:</p>

  <pre>switch $cxx.target.cpu: regex.match icase
{
  ...
}</pre>

  <p>Other commonly used match functions are <code>regex.search()</code>
  (similar to <code>regex.match()</code> but searches for any match rather
  than matching the whole value), <code>path.match()</code> (match using shell
  wildcard patterns) and <code>string.icasecmp()</code> (match using equality
  but ignoring case). Additionally, any other function that takes the value as
  its first argument, the pattern as its second, and returns <code>bool</code>
  can be used as a match function.</p>

  <div class="note">
  <p>Note that there is no special wildcard or match-anything pattern at the
  syntax level. In most common cases the desired semantics can be achieved
  with <code>default</code> and/or by omitting trailing patterns. If you do
  need it, then we recommend using <code>path.match()</code> and its
  <code>*</code> wildcard. For example:</p>

  <pre>switch $cxx.target.class: path.match, \
       $cxx.target.system: path.match, \
       $cxx.id: path.match
{
  case 'windows', '*', 'clang'
    ...
}</pre>
  </div>

  <p>Note also that similar to <code>if-else</code>, there is no notion of
  variable locality in the <code>switch</code> and <code>case-default</code>
  blocks and any value set inside is visible outside. Additionally, the same
  considerations about conditional dependency declarations apply.</p>

  <h3 id="intro-for">1.8.4 Repetitions (<code>for</code>)</h3>

  <p>The <code>for</code> directive can be used to repeat the same
  <code>buildfile</code> fragment multiple times, once for each element of a
  list. The fragment to repeat can be a single (separate) line or a block,
  which together form the <code>for</code> loop. A <code>for</code> block can
  contain nested <code>for</code> loops. For example:</p>

  <pre>for n: foo bar baz
{
  exe{$n}: cxx{$n}
}</pre>

  <p>The <code>for</code> directive name must be followed by the variable name
  (called <i>loop variable</i>) that on each iteration will be assigned the
  corresponding element, <code>:</code>, and an expression that expands to a
  potentially empty list of values. This can be a variable expansion, a
  function call, an eval context, or a literal list as in the above fragment.
  Here is a somewhat more realistic example that splits a space-separated
  environment variable value into names and then generates a dependency
  declaration for each of them:</p>

  <pre>for n: $regex.split($getenv(NAMES), ' +', '')
{
  exe{$n}: cxx{$n}
}</pre>

  <p>Note also that there is no notion of variable locality in
  <code>for</code> blocks and any value set inside is visible outside. At the
  end of the iteration the loop variable contains the value of the last
  element, if any. For example:</p>

  <pre>for x: x X
{
  y = Y
}

info $x  # Prints 'X'.
info $y  # Prints 'Y'.</pre>

  <h2 id="intro-unit-test">1.9 Implementing Unit Testing</h2>

  <p>As an example of how many of these features fit together to implement
  more advanced functionality, let's examine a <code>buildfile</code> that
  provides support for unit testing. This support is added by the <a
  href="../../bdep/doc/bdep-new.xhtml"><code><b>bdep-new(1)</b></code></a>
  command if we specify the <code>unit-tests</code> option when creating
  executable (<code>-t&#160;exe,unit-tests</code>) or library
  (<code>-t&#160;lib,unit-tests</code>) projects. Here is the source
  subdirectory <code>buildfile</code> of an executable created with this
  option:</p>

  <pre>./: exe{hello}: libue{hello}: {hxx cxx}{** -**.test...}

# Unit tests.
#
exe{*.test}:
{
  test = true
  install = false
}

for t: cxx{**.test...}
{
  d = $directory($t)
  n = $name($t)...

  ./: $d/exe{$n}: $t $d/hxx{+$n} $d/testscript{+$n}
  $d/exe{$n}: libue{hello}: bin.whole = false
}

cxx.poptions =+ "-I$out_root" "-I$src_root"</pre>

  <p>The basic idea behind this unit testing arrangement is to keep unit tests
  next to the source code files that they test and automatically recognize and
  build them into test executables without having to manually list each in the
  <code>buildfile</code>. Specifically, if we have <code>hello.hxx</code> and
  <code>hello.cxx</code>, then to add a unit test for this module all we have
  to do is drop the <code>hello.test.cxx</code> source file next to them and
  it will be automatically picked up, built into an executable, and run during
  the <code>test</code> operation.</p>

  <p>As an example, let's say we've renamed <code>hello.cxx</code> to
  <code>main.cxx</code> and factored the printing code into the
  <code>hello.hxx/hello.cxx</code> module that we would like to unit-test.
  Here is the new layout:</p>

  <pre>hello/
├── build
│   └── ...
├── hello
│   ├── hello.cxx
│   ├── hello.hxx
│   ├── hello.test.cxx
│   ├── main.cxx
│   └── buildfile
└── ...</pre>

  <p>Let's examine how this support is implemented in our
  <code>buildfile</code>, line by line. Because now we link
  <code>hello.cxx</code> object code into multiple executables (unit tests and
  the <code>hello</code> program itself), we have to place it into a
  <i>utility library</i>. This is what the first line does (it has to
  explicitly list <code>exe{hello}</code> as a prerequisite of the default
  targets since we now have multiple targets that should be built by
  default):</p>

  <pre>./: exe{hello}: libue{hello}: {hxx cxx}{** -**.test...}</pre>

  <p>A utility library (<code><b>u</b></code> in <code>lib<b>u</b>e</code>) is
  a static library that is built for a specific type of a <i>primary
  target</i> (<code><b>e</b></code> in <code>libu<b>e</b></code> for
  executable). If we were building a utility library for a library then we
  would have used the <code>libul{}</code> target type instead. In fact, this
  would be the only difference in the above unit testing implementation if it
  were for a library project instead of an executable:</p>

  <pre>./: lib{hello}: libul{hello}: {hxx cxx}{** -**.test...}

...

# Unit tests.
#
...

for t: cxx{**.test...}
{
  ...

  $d/exe{$n}: libul{hello}: bin.whole = false
}</pre>

  <p>Going back to the first three lines of the executable
  <code>buildfile</code>, notice that we had to exclude source files in the
  <code>*.test.cxx</code> form from the utility library. This makes sense
  since we don't want unit testing code (each with its own
  <code>main()</code>) to end up in the utility library.</p>

  <p>The exclusion pattern, <code>-**.test...</code>, looks a bit cryptic.
  What we have here is a second-level extension (<code>.test</code>) which we
  use to classify our source files as belonging to unit tests. Because it is a
  second-level extension, we have to indicate this fact to the pattern
  matching machinery with the trailing triple dot (meaning "there are more
  extensions coming"). If we didn't do that, <code>.test</code> would have
  been treated as a first-level extension explicitly specified for our source
  files (see <a href="#targets-types">Target Types</a> for details).</p>

  <p>The next couple of lines set target type/pattern-specific variables to
  treat all unit test executables as tests that should not be installed:</p>

  <pre>exe{*.test}:
{
  test = true
  install = false
}</pre>

  <div class="note">
  <p>You may be wondering why we had to escape the second-level
  <code>.test</code> extension in the name pattern above but not here. The
  answer is that these are different kinds of patterns in different contexts.
  In particular, patterns in the target type/pattern-specific variables are
  only matched against target names without regard for extensions. See <a
  href="#name-patterns">Name Patterns</a> for details.</p>
  </div>

  <p>Then we have the <code>for</code>-loop that declares an executable target
  for each unit test source file. The list of these files is generated with a
  name pattern that is the inverse of what we've used for the utility
  library:</p>

  <pre>for t: cxx{**.test...}
{
  d = $directory($t)
  n = $name($t)...

  ./: $d/exe{$n}: $t $d/hxx{+$n} $d/testscript{+$n}
  $d/exe{$n}: libue{hello}: bin.whole = false
}</pre>

  <p>In the loop body we first split the test source file into the directory
  (remember, we can have sources, including tests, in subdirectories) and name
  (which contains the <code>.test</code> second-level extension and which we
  immediately escape with <code>...</code>). And then we use these components
  to declare a dependency for the corresponding unit test executable. There is
  nothing here that we haven't already seen except for using variable
  expansions instead of literal names.</p>

  <p>By default utility libraries are linked in the "whole archive" mode where
  every object file from the static library ends up in the resulting
  executable or library. This behavior is what we want when linking the
  primary target but can normally be relaxed for unit tests to speed up
  linking. This is what the last line in the loop does using the
  <code>bin.whole</code> prerequisite-specific variable.</p>

  <div class="note">
  <p>You can easily customize this and other aspects on a test-by-test basis
  by excluding the specific test(s) from the loop and then providing a custom
  implementation. For example:</p>

  <pre>for t: cxx{**.test... -special.test...}
{
  ...
}

./: exe{special.test...}: cxx{special.test...} libue{hello}</pre>

  <p>Note also that if you plan to link any of your unit tests in the whole
  archive mode, then you will also need to exclude the source file containing
  the primary executable's <code>main()</code> from the utility library. For
  example:</p>

  <pre>./: exe{hello}: cxx{main} libue{hello}
libue{hello}: {hxx cxx}{** -main -**.test...}</pre>
  </div>

  <h2 id="intro-diag-debug">1.10 Diagnostics and Debugging</h2>

  <p>Sooner or later we will run into a situation where our
  <code>buildfiles</code> don't do what we expect them to. In this section we
  examine a number of techniques and mechanisms that can help us understand
  the cause of a misbehaving build.</p>

  <p>To perform a build the build system goes through several phases. During
  the <i>load</i> phase the <code>buildfiles</code> are loaded and processed.
  The result of this phase is the in-memory <i>build state</i> that contains
  the scopes, targets, variables, etc., defined by the
  <code>buildfiles</code>. Next is the <i>match</i> phase during which rules
  are matched to the targets that need to be built, recursively. Finally,
  during the <i>execute</i> phase the matched rules are executed to perform
  the build.</p>

  <p>The load phase is always serial and stops at the first error. In
  contrast, by default, both match and execute are parallel and continue in
  the presence of errors (similar to the "keep going" <code>make</code> mode).
  While beneficial in normal circumstances, during debugging this can lead to
  both interleaved output that is hard to correlate as well as extra noise
  from cascading errors. As a result, for debugging, it is usually helpful to
  run serially and stop at the first error, which can be achieved with the
  <code>--serial-stop|-s</code> option.</p>

  <div class="note">
  <p>The match phase can be temporarily switched to either (serial) load or
  (parallel) execute. The former is used, for example, to load additional
  <code>buildfiles</code> during the <code>dir{}</code> prerequisite to target
  resolution, as described in <a href="#intro-dirs-scopes">Output Directories
  and Scopes</a>. While the latter is used to update generated source code
  (such as headers) that is required to complete the match.</p>
  </div>

  <p>Debugging issues in each phase requires different techniques. Let's start
  with the load phase. As mentioned in <a href="#intro-lang">Buildfile
  Language</a>, <code>buildfiles</code> are processed linearly with directives
  executed and variables expanded as they are encountered. As we have already
  seen, to print a variable value we can use the <code>info</code> directive.
  For example:</p>

  <pre>x = X
info $x</pre>

  <p>This will print something along these lines:</p>

  <pre>buildfile:2:1: info: X</pre>

  <p>Or, if we want to clearly see where the value begins and ends (useful
  when investigating whitespace-related issues):</p>

  <pre>x = " X "
info "'$x'"</pre>

  <p>Which prints:</p>

  <pre>buildfile:2:1: info: ' X '</pre>

  <p>Besides the <code>info</code> directive, there are also
  <code>text</code>, which doesn't print the <code>info:</code> prefix,
  <code>warn</code>, which prints a warning, as well as <code>fail</code>
  which prints an error and causes the build system to exit with an error.
  Here is an example of using each:</p>

  <pre>text 'note: we are about to get an error'
warn 'the error is imminent'
fail 'this is the end'
info 'we will never get here'</pre>

  <p>This will produce the following output:</p>

  <pre>buildfile:1:1: note: we are about to get an error
buildfile:2:1: warning: the error is imminent
buildfile:3:1: error: this is the end</pre>

  <p>If you find yourself writing code like this:</p>

  <pre>if ($cxx.target.class == 'windows')
  fail 'Windows is not supported'</pre>

  <p>Then the <code>assert</code> directive is a more concise way to express
  the same:</p>

  <pre>assert ($cxx.target.class != 'windows') 'Windows is not supported'</pre>

  <p>The assert condition must be an expression that evaluates to
  <code>true</code> or <code>false</code>, similar to the <code>if</code>
  directive (see <a href="#intro-if-else">Conditions
  (<code>if-else</code>)</a> for details). The description after the condition
  is optional and, similar to <code>if</code>, there is also the
  <code>assert!</code> variant, which fails if the condition is
  <code>true</code>.</p>

  <p>All the diagnostics directives write to <code>stderr</code>. If instead
  we need to write something to <code>stdout</code> to, for example, send some
  information back to our caller, then we can use the <code>print</code>
  directive. For example, this will print the C++ compiler id and its
  target:</p>

  <pre>print "$cxx.id $cxx.target"</pre>

  <div class="note">
  <p>To query the value of a target-specific variable we use the qualified
  name syntax (the <code>eval-qual</code> production) of eval context, for
  example:</p>

  <pre>obj{main}: cxx.poptions += -DMAIN
info $(obj{main}: cxx.poptions)</pre>

  <p>There is no direct way to query the value of a prerequisite-specific
  variable since a prerequisite has no identity. Instead, we can use the
  <code>dump</code> directive discussed next to print the entire dependency
  declaration, including prerequisite-specific variables for each
  prerequisite.</p>
  </div>

  <p>While printing variable values is the most common mechanism for
  diagnosing <code>buildfile</code> issues, sometimes it is also helpful to
  examine targets and scopes. For that we use the <code>dump</code>
  directive.</p>

  <p>Without any arguments, <code>dump</code> prints (to <code>stderr</code>)
  the contents of the scope it was encountered in and at that point of
  processing the <code>buildfile</code>. Its output includes variables,
  targets and their prerequisites, as well as nested scopes, recursively. As
  an example, let's print the source subdirectory scope of our
  <code>hello</code> executable project. Here is its <code>buildfile</code>
  with the <code>dump</code> directive at the end:</p>

  <pre>exe{hello}: {hxx cxx}{**}

cxx.poptions =+ "-I$out_root" "-I$src_root"

dump</pre>

  <p>This will produce the output along these lines:</p>

  <pre>buildfile:5:1: dump:
  /tmp/hello/hello/
  {
    [strings] cxx.poptions = -I/tmp/hello -I/tmp/hello
    [dir_path] out_base = /tmp/hello/hello/
    [dir_path] src_base = /tmp/hello/hello/

    buildfile{buildfile.}:

    exe{hello.?}: cxx{hello.?}
  }</pre>

  <div class="note">
  <p>The question marks (<code>?</code>) in the dependency declaration mean
  that the file extensions haven't been assigned yet, which happens during the
  match phase.</p>
  </div>

  <p>Instead of printing the entire scope, we can also print individual
  targets by specifying one or more target names in <code>dump</code>. To make
  things more interesting, let's convert our <code>hello</code> project to use
  a utility library, similar to the unit testing setup (<a
  href="#intro-unit-test">Implementing Unit Testing</a>). We will also link to
  the <code>dl</code> library to see an example of a target-specific variable
  being dumped:</p>

  <pre>exe{hello}: libue{hello}: bin.whole = false
exe{hello}: cxx.libs += -ldl
libue{hello}: {hxx cxx}{**}

dump exe{hello}</pre>

  <p>The output will look along these lines:</p>

  <pre>buildfile:5:1: dump:
  /tmp/hello/hello/exe{hello.?}:
  {
    [strings] cxx.libs = -ldl
  }
  /tmp/hello/hello/exe{hello.?}: /tmp/hello/hello/:libue{hello.?}:
  {
    [bool] bin.whole = false
  }</pre>

  <p>The output of <code>dump</code> might look familiar: in <a
  href="#intro-dirs-scopes">Output Directories and Scopes</a> we've used the
  <code>--dump</code> option to print the entire build state, which looks
  pretty similar. In fact, the <code>dump</code> directive uses the same
  mechanism but allows us to print individual scopes and targets from within a
  <code>buildfile</code>.</p>

  <p>There is, however, an important difference to keep in mind:
  <code>dump</code> prints the state of a target or scope at the point in the
  <code>buildfile</code> load phase where it was executed. In contrast, the
  <code>--dump</code> option can be used to print the state after the load
  phase (<code>--dump load</code>) and/or after the match phase (<code>--dump
  match</code>). In particular, the after match printout reflects the changes
  to the build state made by the matching rules, which may include entering of
  additional dependencies, setting of additional variables, resolution of
  prerequisites to targets, assignment of file extensions, etc. As a result,
  while the <code>dump</code> directive should be sufficient in most cases,
  sometimes you may need to use the <code>--dump</code> option to examine the
  build state just before rule execution.</p>

  <div class="note">
  <p>It is possible to limit the output of <code>--dump</code> to specific
  scopes and/or targets with the <code>--dump-scope</code> and
  <code>--dump-target</code> options.</p>
  </div>

  <p>Let's now move from state to behavior. As we already know, to see the
  underlying commands executed by the build system we use the <code>-v</code>
  options (which is equivalent to <code>--verbose&#160;2</code>). Note,
  however, that these are <i>logical</i> rather than actual commands. You can
  still run them and they should produce the desired result, but in reality
  the build system may have achieved the same result in a different way. To
  see the actual commands we use the <code>-V</code> option instead
  (equivalent to <code>--verbose&#160;3</code>). Let's see the difference in
  an example. Here is what building our <code>hello</code> executable with
  <code>-v</code> might look like:</p>

  <pre>$ b -s -v
g++ -o hello.o -c hello.cxx
g++ -o hello hello.o</pre>

  <p>And here is the same build with <code>-V</code>:</p>

  <pre>$ b -s -V
g++ -MD -E -fdirectives-only -MF hello.o.t -o hello.o.ii hello.cxx
g++ -E -fpreprocessed -fdirectives-only hello.o.ii
g++ -o hello.o -c -fdirectives-only hello.o.ii
g++ -o hello hello.o</pre>

  <p>From the second listing we can see that in reality <code>build2</code>
  first partially preprocessed <code>hello.cxx</code> while extracting its
  header dependency information. It then preprocessed it fully, which is used
  to extract module dependency information, calculate the checksum for
  ignorable change detection, etc.  When it comes to producing
  <code>hello.o</code>, the build system compiled the partially preprocessed
  output rather than the original <code>hello.cxx</code>. The end result,
  however, is the same as in the first listing.</p>

  <p>Verbosity level <code>3</code> (<code>-V</code>) also triggers printing
  of the build system module configuration information. Here is what we would
  see for the <code>cxx</code> module:</p>

  <pre>cxx hello@/tmp/hello/
  cxx        g++@/usr/bin/g++
  id         gcc
  version    7.2.0 (Ubuntu 7.2.0-1ubuntu1~16.04)
  major      7
  minor      2
  patch      0
  build      (Ubuntu 7.2.0-1ubuntu1~16.04)
  signature  gcc version 7.2.0 (Ubuntu 7.2.0-1ubuntu1~16.04)
  checksum   09b3b59d337eb9a760dd028fa0df585b307e6a49c2bfa00b3[...]
  target     x86_64-linux-gnu
  runtime    libgcc
  stdlib     libstdc++
  c stdlib   glibc
...</pre>

  <p>Verbosity levels higher than <code>3</code> enable build system tracing.
  In particular, level <code>4</code> is useful for understanding why a rule
  doesn't match a target or if it does, why it determined the target to be out
  of date. For example, assuming we have an up-to-date build of our
  <code>hello</code>, let's change a compile option:</p>

  <pre>$ b -s --verbose 4
info: /tmp/hello/dir{hello/} is up to date

$ b -s --verbose 4 config.cxx.poptions+=-DNDEBUG
trace: cxx::compile_rule::apply: options mismatch forcing update
of /tmp/hello/hello/obje{hello.o}
...</pre>

  <p>Higher verbosity levels result in more and more tracing statements being
  printed. These include <code>buildfile</code> loading and parsing,
  prerequisite to target resolution, as well as build system module and
  rule-specific logic.</p>

  <p>While the tracing statements can be helpful in understanding what is
  happening, they don't make it easy to see why things are happening a certain
  way. In particular, one question that is often encountered during build
  troubleshooting is which dependency chain causes matching or execution of a
  particular target. These questions can be answered with the help of the
  <code>--trace-match</code> and <code>--trace-execute</code> options. For
  example, if we want to understand what causes the update of
  <code>obje{hello}</code> in the <code>hello</code> project above:</p>

  <pre>$ b -s --trace-execute 'obje{hello}'
info: updating hello/obje{hello}
  info: using rule cxx.compile
  info: while updating hello/libue{hello}
  info: while updating hello/exe{hello}
  info: while updating dir{hello/}
  info: while updating dir{./}</pre>

  <p>Another useful diagnostics option is <code>--mtime-check</code>. When
  specified, the build system performs a number of file modification time
  sanity checks that can be helpful in diagnosing spurious rebuilds.</p>

  <p>If neither state dumps nor behavior analysis are sufficient to understand
  the problem, there is always an option of running the build system under a
  C++ debugger in order to better understand what's going on. This can be
  particularly productive for debugging complex rules.</p>

  <p>Finally, to help with diagnosing the build system performance issues,
  there is the <code>--stat</code> option. It causes <code>build2</code> to
  print various execution statistics which can be useful for pin-pointing the
  bottlenecks. There are also a number of options for tuning the build
  system's performance, such as, the number of jobs to perform in parallel,
  the stack size, queue depths, etc. See the <a
  href="b.xhtml"><code><b>b(1)</b></code></a> man pages for details.</p>

  <h1 id="proj-config">2 Project Configuration</h1>

  <p>As discussed in the introduction (specifically, <a
  href="#intro-proj-struct">Project Structure</a>) support for build
  configurations is an integral part of <code>build2</code> with the same
  mechanism used by the build system core (for example, for project
  importation via the <code>config.import.*</code> variables), by the build
  system modules (for example, for supplying compile options such as
  <code>config.cxx.coptions</code>), as well as by our projects to provide any
  project-specific configurability. Project configuration is the topic of this
  chapter.</p>

  <div class="note">
  <p>The <code>build2</code> build system currently provides no support for
  <code>autoconf</code>-style probing of the build environment in order to
  automatically discover available libraries, functions, features, etc.</p>

  <p>The main reason for omitting this support is the fundamental ambiguity
  and the resulting brittleness of such probing due to the reliance on
  compiler, linker, or test execution failures. Specifically, in many such
  tests it is impossible for a build system to distinguish between a missing
  feature, a broken test, and a misconfigured build environment. This leads to
  requiring a user intervention in the best case and to a silently
  misconfigured build in the worst. Other issues with this approach include
  portability, speed (compiling and linking takes time), as well as limited
  applicability during cross-compilation (specifically, inability to run
  tests).</p>

  <p>As a result, we recommend using <i>expectation-based</i> configuration
  where your project assumes a feature to be available if certain conditions
  are met. Examples of such conditions at the source code level include
  feature test macros, platform macros, runtime library macros, compiler
  macros, etc., with the build system modules exposing some of the same
  information via variables to allow making similar decisions in
  <code>buildfiles</code>. The standard pre-installed <a
  href="https://github.com/build2/libbuild2-autoconf/"><code>autoconf</code></a>
  build system module provides emulation of GNU <code>autoconf</code> using
  this approach.</p>

  <p>Another alternative is to automatically adapt to missing features using
  more advanced techniques such as C++ SFINAE. And in situations where none of
  this is possible, we recommend delegating the decision to the user via a
  configuration value.  Our experience with <code>build2</code> as well as
  those of other large cross-platform projects such as Boost show that this is
  a viable strategy.</p>

  <p>Having said that, <code>build2</code> does provide the ability to extract
  configuration information from the environment (<code>$getenv()</code>
  function) or other tools (<code>$process.run*()</code> family of functions).
  Note, however, that for this to work reliably there should be no ambiguity
  between the "no configuration available" case (if such a case is possible)
  and the "something went wrong" case. We show a realistic example of this in
  <a href="#proj-config-report">Configuration Report</a> where we extract the
  GCC plugin directory while dealing with the possibility of it being
  configured without plugin support.</p>
  </div>

  <p>Before we delve into the technical details, let's discuss the overall
  need for project configurability. While it may seem that making one's
  project more user-configurable is always a good idea, there are costs: by
  having a choice we increase the complexity and open the door for potential
  incompatibility. Specifically, we may end up with two projects in the same
  build needing a shared dependency with incompatible configurations.</p>

  <div class="note">
  <p>While some languages, such as Rust, support having multiple
  differently-configured projects in the same build, this is not something
  that is done often in C/C++. This ability is also not without its drawbacks,
  most notably code bloat.</p>
  </div>

  <p>As a result, our recommendation is to strive for simplicity and avoid
  user configurability whenever possible. For example, there is a common
  desire to make certain functionality optional in order not to make the user
  pay for things they don't need. This, however, is often better addressed
  either by always providing the optional functionality if it's fairly small
  or by factoring it into a separate project if it's substantial. If a
  configuration value is to be provided, it should have a sensible default
  with a bias for simplicity and compatibility rather than the optimal result.
  For example, in the optional functionality case, the default should probably
  be to provide it.</p>

  <p>As discussed in the introduction, the central part of the build
  configuration functionality are the <i>configuration variables</i>. One of
  the key features that make them special is support for automatic persistence
  in the <code>build/config.build</code> file provided by the <a
  href="#module-config"><code>config</code></a> module (see <a
  href="#intro-operations-config">Configuring</a> for details).</p>

  <div class="note">
  <p>Another mechanism that can be used for project configuration is
  environment variables. While not recommended, sometimes it may be forced on
  us by external factors. In such cases, environment variables that affect the
  build result should be reported with the <code>config.environment</code>
  directive as discussed in <a href="#module-config-hermetic">Hermetic Build
  Configurations</a>.</p>
  </div>

  <p>The following example, based on the <code>libhello</code> project from
  the introduction, gives an overview of the project configuration
  functionality with the remainder of the chapter providing the detailed
  explanation of all the parts shown as well as the alternative
  approaches.</p>

  <pre>libhello/
├── build/
│   ├── root.build
│   └── ...
├── libhello/
│   ├── hello.cxx
│   ├── buildfile
│   └── ...
└── ...</pre>

  <pre># build/root.build

config [string] config.libhello.greeting ?= 'Hello'</pre>

  <pre># libhello/buildfile

cxx.poptions += "-DLIBHELLO_GREETING=\"$config.libhello.greeting\""</pre>

  <pre>// libhello/hello.cxx

void say_hello (ostream&amp; o, const string&amp; n)
{
  o &lt;&lt; LIBHELLO_GREETING ", " &lt;&lt; n &lt;&lt; '!' &lt;&lt; endl;
}</pre>

  <pre>$ b configure config.libhello.greeting=Hi -v
config libhello@/tmp/libhello/
  greeting   Hi

$ cat build/config.build
config.libhello.greeting = Hi

$ b -v
g++ ... -DLIBHELLO_GREETING="Hi" ...</pre>

  <p>By (enforced) convention, configuration variables start with
  <code>config.</code>, for example, <code>config.import.libhello</code>. In
  case of a build system module, the second component in its configuration
  variables should be the module name, for example, <code>config.cxx</code>,
  <code>config.cxx.coptions</code>. Similarly, project-specific configuration
  variables should have the project name as their second component, for
  example, <code>config.libhello.greeting</code>.</p>

  <div class="note">
  <p>More precisely, a project configuration variable must match the
  <code>config[.**].&lt;project>.**</code> pattern where additional components
  may be present after <code>config.</code> in case of subprojects. Overall,
  the recommendation is to use hierarchical names, such as
  <code>config.libcurl.tests.remote</code> for subprojects, similar to build
  system submodules.</p>

  <p>If a build system module for a tool (such as a source code generator) and
  the tool itself share a name, then they may need to coordinate their
  configuration variable names in order to avoid clashes. Note also that when
  importing an executable target in the
  <code>&lt;project>%exe{&lt;project>}</code> form, the
  <code>config.&lt;project></code> variable is treated as an alias for
  <code>config.import.&lt;project>.&lt;project>.exe</code>.</p>

  <p>For an imported <code>buildfile</code>, <code>&lt;project></code> may
  refer to either the importing project or the project from which the said
  <code>buildfile</code> was imported.</p>

  <p>The build system core reserves <code>build</code> and <code>import</code>
  as the second component in configuration variables as well as
  <code>configured</code> as the third and subsequent components.</p>
  </div>

  <p>A variable in the <code>config.&lt;project>.develop</code> form has
  pre-defined semantics: it allows a project to distinguish between
  <i>development</i> and <i>consumption</i> builds. While normally there is no
  distinction between these two modes, sometimes a project may need to provide
  additional functionality during development. For example, a source code
  generator which uses its own generated code in its implementation may need
  to provide a bootstrap step from the pre-generated code. Normally, such a
  step is only needed during development.</p>

  <div class="note">
  <p>While some communities, such as Rust, believe that building and running
  tests is only done during development, we believe its reasonable for an
  end-user to want to run tests for all their dependencies. As a result, we
  strongly discourage restricting tests to the development mode only. Test are
  an integral part of the project and should always be available.</p>
  </div>

  <p>If used, the <code>config.&lt;project>.develop</code> variable should be
  explicitly defined by the project with the <code>bool</code> type and the
  <code>false</code> default value. For example:</p>

  <pre># build/root.build

config [bool] config.libhello.develop ?= false</pre>

  <div class="note">
  <p>If the <code>config.&lt;project>.develop</code> variable is specified by
  the user of the project but the project does not define it (that is, the
  project does not distinguish between development and consumption), then this
  variable is silently ignored. By default <a
  href="../../bdep/doc/bdep-init.xhtml"><code><b>bdep-init(1)</b></code></a>
  configures projects being initialized for development. This can be
  overridden with explicit <code>config.&lt;project>.develop=false</code>.</p>
  </div>

  <h2 id="proj-config-directive">2.1 <code>config</code> Directive</h2>

  <p>To define a project configuration variable we add the <code>config</code>
  directive into the project's <code>build/root.build</code> file (see <a
  href="#intro-proj-struct">Project Structure</a>). For example:</p>

  <pre>config [bool]   config.libhello.fancy    ?= false
config [string] config.libhello.greeting ?= 'Hello'</pre>

  <div class="note">
  <p>The irony does not escape us: these configuration variables are exactly
  of the kind that we advocate against. However, finding a reasonable example
  of build-time configurability in a <i>"Hello, World!"</i> library is not
  easy. In fact, it probably shouldn't have any. So, for this chapter, do as
  we say, not as we do.</p>
  </div>

  <p>Similar to <code>import</code> (see <a href="#intro-import">Target
  Importation</a>), the <code>config</code> directive is a special kind of
  variable assignment. Let's examine all its parts in turn.</p>

  <p>First comes the optional list of variable attributes inside
  <code>[&#160;]</code>. The only attribute that we have in the above example
  is the variable type, <code>bool</code> and <code>string</code>,
  respectively. It is generally a good idea to assign static types to
  configuration variables because their values will be specified by the users
  of our project and the more automatic validation we provide the better (see
  <a href="#variables">Variables</a> for the list of available types). For
  example, this is what will happen if we misspell the value of the
  <code>fancy</code> variable:</p>

  <pre>$ b configure config.libhello.fancy=fals
error: invalid bool value 'fals' in variable config.libhello.fancy</pre>

  <p>After the attribute list we have the variable name. The
  <code>config</code> directive will validate that it matches the
  <code>config[.**].&lt;project>.**</code> pattern (with one exception
  discussed in <a href="#proj-config-report">Configuration Report</a>).</p>

  <p>Finally, after the variable name comes the optional default value. Note
  that unlike normal variables, the default value assignment (<code>?=</code>)
  is the only valid form of assignment in the <code>config</code>
  directive.</p>

  <p>The semantics of the <code>config</code> directive is as follows: First
  an overridable variable is entered with the specified name, type (if any),
  and global visibility. Then, if the variable is undefined and the default
  value is specified, it is assigned the default value. After this, if the
  variable is defined (either as user-defined or default), it is marked for
  persistence. Finally, a defined variable is also marked for reporting as
  discussed in <a href="#proj-config-report">Configuration Report</a>. Note
  that if the variable is user-defined, then the default value is not
  evaluated.</p>

  <p>Note also that if the configuration value is not specified by the user
  and you haven't provided the default, the variable will be undefined, not
  <code>null</code>, and, as a result, omitted from the persistent
  configuration (<code>build/config.build</code> file). In fact, unlike other
  variables, project configuration variables are by default not
  <i>nullable</i>. For example:</p>

  <pre>$ b configure config.libhello.fancy=[null]
error: null value in non-nullable variable config.libhello.fancy</pre>

  <p>There are two ways to make <code>null</code> a valid value of a project
  configuration variable. Firstly, if the default value is <code>null</code>,
  then naturally the variable is assumed nullable. This is traditionally used
  for <i>optional</i> configuration values. For example:</p>

  <pre>config [string] config.libhello.fallback_name ?= [null]</pre>

  <p>If we need a nullable configuration variable but with a
  non-<code>null</code> default value (or no default value at all), then we
  have to use the <code>null</code> variable attribute. For example:</p>

  <pre>config [string, null] config.libhello.fallback_name ?= "World"</pre>

  <p>A common approach for representing an C/C++ enum-like value is to use
  <code>string</code> as a type and pattern matching for validation. In fact,
  validation and propagation can often be combined. For example, if our
  library needed to use a database for some reason, we could handle it like
  this:</p>

  <pre>config [string] config.libhello.database ?= [null]

using cxx

switch $config.libhello.database
{
  case [null]
  {
    # No database in use.
  }
  case 'sqlite'
  {
    cxx.poptions += -DLIBHELLO_WITH_SQLITE
  }
  case 'pgsql'
  {
    cxx.poptions += -DLIBHELLO_WITH_PGSQL
  }
  default
  {
    fail "invalid config.libhello.database value \
'$config.libhello.database'"
  }
}</pre>

  <p>While it is generally a good idea to provide a sensible default for all
  your configuration variables, if you need to force the user to specify its
  value explicitly, this can be achieved with an extra check. For example:</p>

  <pre>config [string] config.libhello.database

if! $defined(config.libhello.database)
  fail 'config.libhello.database must be specified'</pre>

  <div class="note">
  <p>A configuration variable without a default value is omitted from
  <code>config.build</code> unless the value is specified by the user. This
  semantics is useful for values that are normally derived from other
  configuration values but could also be specified by the user. If the value
  is derived, then we don't want it saved in <code>config.build</code> since
  that would prevent it from being re-derived if the configuration values it
  is based on are changed. For example:</p>

  <pre>config [strings] config.hello.database

assert ($size($config.hello.database) > 0) \
  'database must be specified with config.hello.database'

config [bool, config.report.variable=multi] config.hello.multi_database

multi = ($defined(config.hello.multi_database) \
         ? $config.hello.multi_database        \
         : $size(config.hello.database) > 1)

assert ($multi || $size(config.hello.database) == 1) \
  'one database can be specified if config.hello.multi_database=false'</pre>
  </div>

  <p>If computing the default value is expensive or requires elaborate logic,
  then the handling of a configuration variable can be broken down into two
  steps along these lines:</p>

  <pre>config [string] config.libhello.greeting

if! $defined(config.libhello.greeting)
{
  greeting = ... # Calculate default value.

  if ($greeting == [null])
    fail "unable to calculate default greeting, specify manually \
with config.libhello.greeting"

  config config.libhello.greeting ?= $greeting
}</pre>

  <p>Other than assigning the default value via the <code>config</code>
  directive, configuration variables should not be modified by the project's
  <code>buildfiles</code>. Instead, if further processing of the configuration
  value is necessary, we should assign the configuration value to a different,
  non-<code>config.*</code>, variable and modify that. The two situations
  where this is commonly required are post-processing of configuration values
  to be more suitable for use in <code>buildfiles</code> as well as further
  customization of configuration values. Let's see examples of both.</p>

  <p>To illustrate the first situation, let's say we need to translate the
  database identifiers specified by the user:</p>

  <pre>config [string] config.libhello.database ?= [null]

switch $config.libhello.database
{
  case [null]
    database = [null]

  case 'sqlite'
    database = 'SQLITE'

  case 'pgsql'
    database = 'PGSQL'

  case 'mysql'
  case 'mariadb'
    database = 'MYSQL'

  default
    fail "..."
  }
}

using cxx

if ($database != [null])
  cxx.poptions += "-DLIBHELLO_WITH_$database"</pre>

  <p>For the second situation, the typical pattern looks like this:</p>

  <pre>config [strings] config.libhello.options

options  = # Overridable options go here.
options += $config.libhello.options
options += # Non-overridable options go here.</pre>

  <p>That is, assuming that the subsequently specified options (for example,
  command line options) override any previously specified, we first set
  default <code>buildfile</code> options that are allowed to be overridden by
  options from the configuration value, then append such options, if any, and
  finish off by appending <code>buildfile</code> options that should always be
  in effect.</p>

  <p>As a concrete example of this approach, let's say we want to make the
  compiler warning level of our project configurable (likely a bad idea; also
  ignores compiler differences):</p>

  <pre>config [strings] config.libhello.woptions

woptions  = -Wall -Wextra
woptions += $config.libhello.woptions
woptions += -Werror

using cxx

cxx.coptions += $woptions</pre>

  <p>With this arrangement, the users of our project can customize the warning
  level but cannot disable the treatment of warnings as errors. For
  example:</p>

  <pre>$ b -v config.libhello.woptions=-Wno-extra
g++ ... -Wall -Wextra -Wno-extra -Werror ...</pre>

  <p>If you do not plan to package your project, then the above rules are the
  only constraints you have. However, if your project is also a package, then
  other projects that use it as a dependency may have preferences and
  requirements regarding its configuration. And it becomes the job of the
  package manager (<code>bpkg</code>) to negotiate a suitable configuration
  between all the dependents of your project (see <a
  href="../../bpkg/doc/build2-package-manager-manual.xhtml#dep-config-negotiation">Dependency
  Configuration Negotiation</a> for details). This can be a difficult problem
  to solve optimally in a reasonable time and to help the package manager come
  up with the best configuration quickly you should follow the below
  additional rules and recommendations for configuration of packages (but
  which are also generally good ideas):</p>

  <ol>
  <li>Prefer <code>bool</code> configuration variables. For example, if your
  project supports a fixed number of backends, then provide a
  <code>bool</code> variable to enable each rather than a single variable that
  lists all the backends to be enabled.</li>

  <li>Avoid project configuration variable dependencies, that is, where the
  default value of one variable depends on the value of another. But if you do
  need such a dependency, make sure it is expressed using the original
  <code>config.&lt;project>.*</code> variables rather than any
  intermediate/computed values. For example:

  <pre># Enable Y only if X is enabled.
#
config [bool] config.hello.x ?= false
config [bool] config.hello.y ?= $config.libhello.x</pre></li>

  <li>Do not make project configuration variables conditional. In other words,
  the set of configuration variables and their types should be a static
  property of the project. If you do need to make a certain configuration
  variable "unavailable" or "disabled" if certain conditions are met (for
  example, on a certain platform or based on the value of another
  configuration variable), then express this with a default value and/or a
  check. For example:

  <pre>windows = ($cxx.target.class == 'windows')

# Y should only be enabled if X is enabled and we are not on
# Windows.
#
config [bool] config.hello.x ?= false
config [bool] config.hello.y ?= ($config.hello.x &amp;&amp; !$windows)

if $config.libhello.y
{
  assert $config.hello.x "Y can only be enabled if X is enabled"
  assert (!$windows)     "Y cannot be enabled on Windows"
}</pre></li>
  </ol>

  <p>Additionally, if you wish to factor some <code>config</code> directives
  into a separate file (for example, if you have a large number of them or you
  would like to share them with subprojects) and source it from your
  <code>build/root.build</code>, then it is recommended that you place this
  file into the <code>build/config/</code> subdirectory, where the package
  manager expects to find such files (see <a
  href="../../bpkg/doc/build2-package-manager-manual.xhtml#package-skeleton">Package
  Build System Skeleton</a> for background). For example:</p>

  <pre># root.build
#

...

source $src_root/build/config/common.build</pre>

  <div class="note">
  <p>If you would prefer to keep such a file in a different location (for
  example, because it contains things other than <code>config</code>
  directives), then you will need to manually list it in your package's
  <code>manifest</code> file, see the <a
  href="../../bpkg/doc/build2-package-manager-manual.xhtml#manifest-package-build-file"><code>build-file</code></a>
  value for details.</p>
  </div>

  <p>Another effect of the <code>config</code> directive is to print the
  configuration variable in the project's configuration report. This
  functionality is discussed in the following section. While we have already
  seen some examples of how to propagate the configuration values to our
  source code, <a href="#proj-config-propag">Configuration Propagation</a>
  discusses this topic in more detail.</p>

  <h2 id="proj-config-report">2.2 Configuration Report</h2>

  <p>One of the effects of the <code>config</code> directive is to mark a
  defined configuration variable for reporting. The project configuration
  report is printed automatically at a sufficiently high verbosity level along
  with the build system module configuration. For example (some of the
  <code>cxx</code> module configuration is omitted for brevity):</p>

  <pre>$ b config.libhello.greeting=Hey -v
cxx libhello@/tmp/libhello/
  cxx        g++@/usr/bin/g++
  id         gcc
  version    9.1.0
  ...
config libhello@/tmp/libhello/
  fancy      false
  greeting   Hey</pre>

  <div class="note">
  <p>The configuration report is printed immediately after loading the
  project's <code>build/root.build</code> file. It is always printed at
  verbosity level <code>3</code> (<code>-V</code>) or higher. It is also
  printed at verbosity level <code>2</code> (<code>-v</code>) if any of the
  reported configuration variables have a <i>new</i> value. A value is
  considered new if it was set to default or was overridden on the command
  line.</p>
  </div>

  <p>The project configuration report header (the first line) starts with the
  special <code>config</code> module name (the <code>config</code> module
  itself does not have a report) followed by the project name and its
  <code>out_root</code> path. After the header come configuration variables
  with the <code>config[.**].&lt;project></code> prefix removed. The
  configuration report for each variable can be customized using a number of
  <code>config.report*</code> attributes as discussed next.</p>

  <p>The <code>config.report</code> attribute controls whether the variable is
  included into the report and, if so, the format to print its value in. For
  example, this is how we can exclude a variable from the report:</p>

  <pre>config [bool, config.report=false] config.libhello.selftest ?= false</pre>

  <p>While we would normally want to report all our configuration variables ,
  if some of them are internal and not meant to be used by the users of our
  project, it probably makes sense to exclude them.</p>

  <p>The only currently supported alternative printing format is
  <code>multiline</code> which prints a list value one element per line. <span
  class="note">Other printing formats may be supported in the future.</span>
  For example:</p>

  <pre>config [dir_paths, config.report=multiline] config.libhello.search_dirs</pre>

  <pre>$ b config.libhello.search_dirs="/etc/default /etc" -v
config libhello@/tmp/libhello/
  search_dirs
    /etc/default/
    /etc/</pre>

  <p>The <code>config.report</code> attribute can also be used to include a
  non-<code>config.*</code> variable into a report. This is primarily useful
  for configuration values that are always discovered automatically but that
  are still useful to report for troubleshooting. Here is a realistic
  example:</p>

  <pre>using cxx

# Determine the GCC plugin directory.
#
if ($cxx.id == 'gcc')
{
  plugin_dir = [dir_path] $process.run($cxx.path -print-file-name=plugin)

  # If plugin support is disabled, then -print-file-name will print
  # the name we have passed (the real plugin directory will always
  # be absolute).
  #
  if ("$plugin_dir" == plugin)
    fail "$recall($cxx.path) does not support plugins"

  config [config.report] plugin_dir
}</pre>

  <div class="note">
  <p>This is the only situation where a variable that does not match the
  <code>config[.**].&lt;project>.**</code> pattern is allowed in the
  <code>config</code> directive. Note also that a value of such a variable is
  never considered new.</p>
  </div>

  <p>Note that this mechanism should not be used to report configuration
  values that require post-processing because of the loss of the new value
  status (unless you are reporting both the original and post-processed
  values). Instead, use the <code>config.report.variable</code> attribute to
  specify an alternative variable for the report. For example:</p>

  <pre>config [strings, config.report.variable=woptions] \
  config.libhello.woptions

woptions  = -Wall -Wextra
woptions += $config.libhello.woptions
woptions += -Werror</pre>

  <pre>$ b config.libhello.woptions=-Wno-extra -v
config libhello@/tmp/libhello/
  woptions   -Wall -Wextra -Wno-extra -Werror</pre>

  <p>The <code>config.report.module</code> attribute can be used to override
  the reporting module name, that is, <code>config</code> in the
  <code>config&#160;libhello@/tmp/libhello/</code> line above. It is primarily
  useful in imported <code>buildfiles</code> that wish to report
  non-<code>config.*</code> variables under their own name. For example:</p>

  <pre>config [string] config.rtos.board

# Load the board description and report key information such as the
# capability revoker.
#
...
revoker = ...

config [config.report.module=rtos] revoker</pre>

  <pre>$ b config.rtos.board=ibex-safe-simulator -v
rtos hello@/tmp/hello/
  board      ibex-safe-simulator
  revoker    hardware</pre>

  <h2 id="proj-config-propag">2.3 Configuration Propagation</h2>

  <p>Using configuration values in our <code>buildfiles</code> is
  straightforward: they are like any other <code>buildfile</code> variables
  and we can access them directly. For example, this is how we could provide
  optional functionality in our library by conditionally including certain
  source files: <span class="note">See <a href="#intro-if-else">Conditions
  (<code>if-else</code>)</a> for why we should not use <code>if</code> to
  implement this.</span></p>

  <pre># build/root.build

config [strings] config.libhello.io ?= true</pre>

  <pre># libhello/buildfile

lib{hello}: {hxx ixx txx cxx}{** -version -hello-io} hxx{version}
lib{hello}: {hxx cxx}{hello-io}: include = $config.libhello.io</pre>

  <p>On the other hand, it is often required to propagate the configuration
  information to our source code. In fact, we have already seen one way to do
  it: we can pass this information via C/C++ preprocessor macros defined on
  the compiler's command line. For example:</p>

  <pre># build/root.build

config [bool]   config.libhello.fancy    ?= false
config [string] config.libhello.greeting ?= 'Hello'</pre>

  <pre># libhello/buildfile

if $config.libhello.fancy
  cxx.poptions += -DLIBHELLO_FANCY

cxx.poptions += "-DLIBHELLO_GREETING=\"$config.libhello.greeting\""</pre>

  <pre>// libhello/hello.cxx

void say_hello (ostream&amp; o, const string&amp; n)
{
#ifdef LIBHELLO_FANCY
  // TODO: something fancy.
#else
  o &lt;&lt; LIBHELLO_GREETING ", " &lt;&lt; n &lt;&lt; '!' &lt;&lt; endl;
#endif
}</pre>

  <p>We can even use the same approach to export certain configuration
  information to our library's users (see <a href="#intro-lib">Library
  Exportation and Versioning</a> for details):</p>

  <pre># libhello/buildfile

# Export options.
#
if $config.libhello.fancy
  lib{hello}: cxx.export.poptions += -DLIBHELLO_FANCY</pre>

  <p>This mechanism is simple and works well across compilers so there is no
  reason not to use it when the number of configuration values passed and
  their size are small. However, it can quickly get unwieldy as these numbers
  grow. For such cases, it may make sense to save this information into a
  separate auto-generated source file with the help of the <a
  href="#module-in"><code>in</code></a> module, similar to how we do it for
  the version header.</p>

  <p>The often-used approach is to generate a header file and include it into
  source files that need access to the configuration information.
  Historically, this was a C header full of macros called
  <code>config.h</code>. However, for C++ projects, there is no reason not to
  make it a C++ header and, if desired, to use modern C++ features instead of
  macros. Which is what we will do here.</p>

  <p>As an example of this approach, let's convert the above command
  line-based implementation to use the configuration header. We will continue
  using macros as a start (or in case this is a C project) and try more modern
  techniques later. The <code>build/root.build</code> file is unchanged except
  for loading the <code>in</code> module:</p>

  <pre># build/root.build

config [bool]   config.libhello.fancy    ?= false
config [string] config.libhello.greeting ?= 'Hello'

using in</pre>

  <p>The <code>libhello/config.hxx.in</code> file is new:</p>

  <pre>// libhello/config.hxx.in

#pragma once

#define LIBHELLO_FANCY    $config.libhello.fancy$
#define LIBHELLO_GREETING "$config.libhello.greeting$"</pre>

  <p>As you can see, we can reference our configuration variables directly in
  the <code>config.hxx.in</code> substitutions (see the <a
  href="#module-in"><code>in</code></a> module documentation for details on
  how this works).</p>

  <div class="note">
  <p>With this setup, the way to export configuration information to our
  library's users is to make the configuration header public and install it,
  similar to how we do it for the version header.</p>
  </div>

  <p>The rest is changed as follows:</p>

  <pre># libhello/buildfile

lib{hello}: {hxx ixx txx cxx}{** -version -config} hxx{version config}

hxx{config}: in{config}
{
  install = false
}</pre>

  <pre>// libhello/hello.cxx

#include &lt;libhello/config.hxx>

void say_hello (ostream&amp; o, const string&amp; n)
{
#if LIBHELLO_FANCY
  // TODO: something fancy.
#else
  o &lt;&lt; LIBHELLO_GREETING ", " &lt;&lt; n &lt;&lt; '!' &lt;&lt; endl;
#endif
}</pre>

  <div class="note">
  <p>Notice that we had to replace <code>#ifdef&#160;LIBHELLO_FANCY</code>
  with <code>#if&#160;LIBHELLO_FANCY</code>. If you want to continue using
  <code>#ifdef</code>, then you will need to make the necessary arrangements
  yourself (the <code>in</code> module is a generic preprocessor and does not
  provide any special treatment for <code>#define</code>). For example:</p>

  <pre>#define LIBHELLO_FANCY $config.libhello.fancy$
#if !LIBHELLO_FANCY
#  undef LIBHELLO_FANCY
#endif</pre>
  </div>

  <p>Now that the macro-based version is working, let's see how we can take
  advantage of modern C++ features to hopefully improve on some of their
  drawbacks. As a first step, we can replace the <code>LIBHELLO_FANCY</code>
  macro with a compile-time constant and use <code>if&#160;constexpr</code>
  instead of <code>#ifdef</code> in our implementation:</p>

  <pre>// libhello/config.hxx.in

namespace hello
{
  inline constexpr bool fancy = $config.libhello.fancy$;
}</pre>

  <pre>// libhello/hello.cxx

#include &lt;libhello/config.hxx>

void say_hello (ostream&amp; o, const string&amp; n)
{
  if constexpr (fancy)
  {
    // TODO: something fancy.
  }
  else
    o &lt;&lt; LIBHELLO_GREETING ", " &lt;&lt; n &lt;&lt; '!' &lt;&lt; endl;
}</pre>

  <div class="note">
  <p>Note that with <code>if&#160;constexpr</code> the branch not taken must
  still be valid, parsable code. This is both one of the main benefits of
  using it instead of <code>#if</code> (the code we are not using is still
  guaranteed to be syntactically correct) as well as its main drawback (it
  cannot be used, for example, for platform-specific code without extra
  efforts, such as providing shims for missing declarations, etc).</p>
  </div>

  <p>Next, we can do the same for <code>LIBHELLO_GREETING</code>:</p>

  <pre>// libhello/config.hxx.in

namespace hello
{
  inline constexpr char greeting[] = "$config.libhello.greeting$";
}</pre>

  <pre>// libhello/hello.cxx

#include &lt;libhello/config.hxx>

void say_hello (ostream&amp; o, const string&amp; n)
{
  if constexpr (fancy)
  {
    // TODO: something fancy.
  }
  else
    o &lt;&lt; greeting &lt;&lt; ", " &lt;&lt; n &lt;&lt; '!' &lt;&lt; endl;
}</pre>

  <div class="note">
  <p>Note that for <code>greeting</code> we can achieve the same result
  without using inline variables or <code>constexpr</code> and which would be
  usable in older C++ and even C. All we have to do is add the
  <code>config.cxx.in</code> source file next to our header with the
  definition of the <code>greeting</code> variable. For example:</p>

  <pre>// libhello/config.hxx.in

namespace hello
{
  extern const char greeting[];
}</pre>

  <pre>// libhello/config.cxx.in

#include &lt;libhello/config.hxx>

namespace hello
{
  const char greeting[] = "$config.libhello.greeting$";
}</pre>

  <pre># libhello/buildfile

lib{hello}: {hxx ixx txx cxx}{** -config} {hxx cxx}{config}

hxx{config}: in{config}
{
  install = false
}

cxx{config}: in{config}</pre>

  <p>As this illustrates, the <code>in</code> module can produce as many
  auto-generated source files as we need. For example, we could use this to
  split the configuration header into two, one public and installed while the
  other private.</p>
  </div>

  <h1 id="targets">3 Targets and Target Types</h1>

  <p><span class="note">This chapter is a work in progress and is
  incomplete.</span></p>

  <h2 id="targets-types">3.1 Target Types</h2>

  <p>A target type is part of a target's identity. The core idea behind the
  concept of target types is to abstract away from file extensions which can
  vary from project to project (for example, C++ source files extensions) or
  from platform to platform (for example, executable file extensions). It also
  allows us to have non-file-based targets.</p>

  <p>Target types form a <i>base-derived</i> inheritance tree. The root of
  this tree is the abstract <code>target{}</code> type. The
  <code>build2</code> core defines a number of standard target types, such as
  <code>file{}</code>, <code>doc{}</code>, and <code>exe{}</code>. Build
  system modules can define additional target types that are based on the
  standard ones (or on types defined by other modules). For example, the
  <code>c</code> module that provides the C compilation support defines the
  <code>h{}</code> and <code>c{}</code> target types. Finally,
  <code>buildfiles</code> can derive project-local target types using the
  <code>define</code> directive.</p>

  <div class="note">
  <p>If a target type represents a file type with a well-established
  extension, then by convention such an extension is used as the target type
  name. For example, the C language header and source files use the
  <code>.h</code> and <code>.c</code> extensions and the target types are
  called <code>h{}</code> and <code>c{}</code>.</p>

  <p>Speaking of conventions, as you may have noticed, when mentioning a
  target type we customarily add <code>{}</code> after its name. We found that
  this helps with comprehension since target type names are often short (you
  can also search for <code>&lt;type>{</code> to narrow it down to target
  types). In a way this is a similar approach to adding <code>()</code> after
  a function name except here we use <code>{}</code>, which mimics target type
  usage in target names, for example <code>c{hello}</code> for
  <code>hello.c</code>.</p>
  </div>

  <p>The following listing shows the hierarchy of the standard target types
  defined by the <code>build2</code> core (the abstract target types are
  marked with <code>*</code>) while the following sections describe each
  standard target type in detail. For target types defined by a module refer
  to the respective module documentation.</p>

  <pre>                   .-----target*------------.
                   |                 |      |
              mtime_target*---.    alias  fsdir
                   |          |      |
              path_target*  group   dir
                   |
        .---------file----.
        |          |      |
  .----doc-----.  exe  buildfile
  |     |      |
legal  man  manifest
        |
       man&lt;N></pre>

  <p>While target types replace (potentially variable) extensions, there still
  needs to be a mechanism for specifying them since in most cases targets have
  to be mapped to files. There are several ways this can be achieved.</p>

  <p>If a target type represents a file type with a well-established
  extension, then such an extension is normally used by default and we don't
  need to take any extra steps. For example the <code>h{}</code> and
  <code>c{}</code> target types for C header and source files default to the
  <code>.h</code> and <code>.c</code> extensions, respectively, and if our
  project follows this convention, then we can simply write:</p>

  <pre>exe{utility}: c{utility} h{utility}</pre>

  <p>And <code>c{utility}</code> will be mapped to <code>utility.c</code> and
  <code>h{utility}</code> &#8211; to <code>utility.h</code>.</p>

  <p>There are two variants of this default extension case: fixed extension
  and customizable extension. A target type may choose to fix the default
  extension if it's a bad idea to deviate from the default extension. A good
  example of such a target is <code>man1{}</code>, which fixes the default
  extension to be <code>.1</code>. More commonly, however, a target will have
  a default extension but will allow customizing it with the
  <code>extension</code> variable.</p>

  <p>A good example where extension customization is often required are the
  <code>hxx{}</code> and <code>cxx{}</code> target types for C++ header and
  source files, which default to the <code>.hxx</code> and <code>.cxx</code>
  extensions, respectively. If our project uses other extensions, for example,
  <code>.hpp</code> and <code>.cpp</code>, then we can adjust the defaults
  (typically done in <code>root.build</code>, after loading the
  <code>cxx</code> module):</p>

  <pre>hxx{*}: extension = hpp
cxx{*}: extension = cpp</pre>

  <p>Then we can write:</p>

  <pre>exe{utility}: cxx{utility} hxx{utility}</pre>

  <p>And <code>cxx{utility}</code> will be mapped to <code>utility.cpp</code>
  and <code>hxx{utility}</code> &#8211; to <code>utility.hpp</code>.</p>

  <p>What about <code>exe{utility}</code>, where does its extension come from?
  This is an example of a target type with an extension that varies from
  platform to platform.  In such cases the extension is expected to be
  assigned by the rule that matches the target. In the above example, the link
  rule from the <code>cxx</code> module that matches updating
  <code>exe{utility}</code> will assign a suitable extension based on the
  target platform of the C++ compiler that it was instructed to use.</p>

  <p>Finally, it is always possible to specify the file extension explicitly
  as part of the target name. For example:</p>

  <pre>exe{utility}: cxx{utility.cc} hxx{utility.hh}</pre>

  <p>This is normally only needed if the default extension is not appropriate
  or if the target type does not have a default extension, as is the case, for
  example, for the <a href="#targets-types-file"><code>file{}</code></a> and
  <a href="#targets-types-doc"><code>doc{}</code></a> target types. This
  mechanism can also be used to override the automatically derived extension.
  For example:</p>

  <pre>exe{($cxx.target.class == 'windows' ? utility.com : utility)}: ...</pre>

  <div class="note">
  <p>If you need to specify a name that does not have an extension, then end
  it with a single dot. For example, for a header <code>utility</code> you
  would write <code>hxx{utility.}</code>. If you need to specify a name with
  an actual trailing dot, then escape it with a double dot, for example,
  <code>hxx{utility..}</code>.</p>

  <p>More generally, anywhere in a name, a double dot can be used to specify a
  dot that should not be considered the extension separator while a triple dot
  &#8211; which should. For example, in <code>obja{foo.a.o}</code> the
  extension is <code>.o</code> and if instead we wanted <code>.a.o</code> to
  be considered the extension, then we could rewrite it either as
  <code>obja{foo.a..o}</code> or as <code>obja{foo...a.o}</code>.</p>
  </div>

  <p>To derive a new target type in a <code>buildfile</code> we use the
  <code>define</code> directive. Such target types are project-local, meaning
  they cannot be exported to other projects. Typically this is used to provide
  a more meaningful name to a set of files and also avoid having to specify
  their extensions explicitly. Compare:</p>

  <pre>./: doc{README.md PACKAGE-README.md INSTALL.md}</pre>

  <p>To:</p>

  <pre>define md: doc
doc{*}: extension = md

./: md{README PACKAGE-README INSTALL}</pre>

  <h3 id="targets-types-target">3.1.1 <code>target{}</code></h3>

  <p>The <code>target{}</code> target type is a root of the target type
  hierarchy. It is abstract and is not commonly used directly, except perhaps
  in patterns (target type/pattern-specific variable, pattern rules).</p>

  <h3 id="targets-types-alias">3.1.2 <code>alias{}</code> and
  <code>dir{}</code></h3>

  <p>The <code>alias{}</code> target type is used for non-file-based targets
  that serve as aliases for their prerequisite.</p>

  <div class="note">
  <p>Alias targets in <code>build2</code> are roughly equivalent to phony
  targets in <code>make</code>.</p>
  </div>

  <p>For example:</p>

  <pre>alias{tests}: exe{test1 test2 test3}</pre>

  <pre>$ b test: alias{tests}</pre>

  <p>An <code>alias{}</code> target can also serve as an "action" if supplied
  with an ad hoc recipe (or matched by an ad hoc pattern rule). For
  example:</p>

  <pre>alias{strip}: exe{hello}
{{
  diag strip $&lt;
  strip $path($&lt;)
}}</pre>

  <p>The <code>dir{}</code> target type is a special kind of alias that
  represents a directory. Building it means building everything inside the
  directory. See <a href="#intro-proj-struct">Project Structure</a> for
  background.</p>

  <p>A target without a type that ends with a directory separator
  (<code>/</code>) is automatically treated as <code>dir{}</code>. For
  example, the following two lines are equivalent:</p>

  <pre>./: exe{test1 test2}
dir{./}: exe{test1 test2}</pre>

  <p>Omitting the target type in such situations is customary.</p>

  <h3 id="targets-types-fsdir">3.1.3 <code>fsdir{}</code></h3>

  <p>The <code>fsdir{}</code> target type represents a filesystem directory.
  Unlike <code>dir{}</code> above, it is not an alias and listing an
  <code>fsdir{}</code> directory as a prerequisite of a target will cause that
  directory to be created on <code>update</code> and removed on
  <code>clean</code>.</p>

  <p>While we usually don't need to list explicit <code>fsdir{}</code>
  prerequisites for our targets, one situation where this is necessary is when
  the target resides in a subdirectory that does not correspond to an existing
  source directory. A typical example of this situation is placing object
  files into subdirectories. Compare:</p>

  <pre>obj{foo}: c{foo}
sub/obj{bar}: c{bar} fsdir{sub/}</pre>

  <h3 id="targets-types-mtime-path">3.1.4 <code>mtime_target{}</code> and
  <code>path_target{}</code></h3>

  <p>The <code>mtime_target{}</code> target type represents a target that uses
  modification times to determine if it is out of date. The
  <code>path_target{}</code> target type represents a target that has a
  corresponding filesystem entry. It is derived from
  <code>mtime_target{}</code> and uses the modification time of that
  filesystem entry to determine if the target is out of date.</p>

  <p>Both of these target types are abstract and are not commonly used
  directly, except perhaps in patterns (target type/pattern-specific variable,
  pattern rules).</p>

  <h3 id="targets-types-group">3.1.5 <code>group{}</code></h3>

  <p>The <code>group{}</code> target type represents a user-defined explicit
  target group, that is, a target that has multiple member targets that are
  all built together with a single recipe.</p>

  <p>Normally this target type is not used to declare targets or prerequisites
  but rather as a base of a derived group. If desired, such a derived group
  can be marked with an attribute as "see-through", meaning that when the
  group is listed as a prerequisite of a target, the matching rule "sees" its
  members, rather than the group itself. For example:</p>

  <pre>define [see_through] thrift_cxx: group</pre>

  <h3 id="targets-types-file">3.1.6 <code>file{}</code></h3>

  <p>The <code>file{}</code> target type represents a generic file. This
  target type is used as a base for most of the file-based targets and can
  also be used to declare targets and prerequisites when there are no more
  specific target types.</p>

  <p>A target or prerequisite without a target type is automatically treated
  as <code>file{}</code>. However, omitting a target type in such situations
  is not customary.</p>

  <p>The <code>file{}</code> target type has no default extension and one
  cannot be assigned with the <code>extension</code> variable. As a result, if
  a <code>file{}</code> target has an extension, then it must be specified
  explicitly as part of the target name. For example:</p>

  <pre>./: file{example.conf}</pre>

  <h3 id="targets-types-doc">3.1.7 <code>doc{}</code>, <code>legal{}</code>,
  and <code>man{}</code></h3>

  <p>The <code>doc{}</code> target type represents a generic documentation
  file. It has semantics similar to <code>file{}</code> (from which it
  derives): it can be used as a base or declare targets/prerequisites and
  there is no default extension.  One notable difference, however, is that
  <code>doc{}</code> targets are by default installed into the
  <code>doc/</code> installation location (see <a
  href="#module-install"><code>install</code> Module</a>). For example:</p>

  <pre>./: doc{README.md ChangeLog.txt}</pre>

  <p>The <code>legal{}</code> target type is derived from <code>doc{}</code>
  and represents a legal documentation file, such as a license, copyright
  notice, authorship information, etc. The main purpose of having a separate
  target type like this is to help with installing licensing-related files
  into a different location. To this effect, <code>legal{}</code> targets are
  installed into the <code>legal/</code> installation location, which by
  default is the same as <code>doc/</code> but can be customized. For
  example:</p>

  <pre>./: legal{COPYRIGHT LICENSE AUTHORS.md}</pre>

  <p>The <code>man{}</code> target type is derived from <code>doc{}</code> and
  represents a manual page. This target type requires an explicit extension
  specification and is installed into the <code>man/</code> installation
  location</p>

  <div class="note">
  <p>If you are using the <code>man{}</code> target type directly (instead of
  one of <code>man&lt;N>{}</code> described below), for example, to install a
  localized version of a man page, then you will likely need to adjust the
  installation location on the per target basis.</p>
  </div>

  <p>The <code>man&lt;N>{}</code> target types (where <code>&lt;N></code> is
  an integer between 1 and 9) are derived from <code>man{}</code> and
  represent manual pages in the respective sections. These target types have
  fixed default extensions <code>.&lt;N></code> (but an explicit extension can
  still be specified, for example <code>man1{foo.1p}</code>) and are installed
  into the <code>man&lt;N>/</code> installation locations. For example:</p>

  <pre>./: man1{foo}</pre>

  <h3 id="targets-types-exe">3.1.8 <code>exe{}</code></h3>

  <p>The <code>exe{}</code> target type represents an executable file.
  Executables in <code>build2</code> appear in two distinct but sometimes
  overlapping contexts: We can build an executable target, for example from C
  source files. Or we can list an executable target as a prerequisite in order
  to execute it as part of a recipe. And sometimes this can be the same
  executable target. For example, one project may build an executable target
  that is a source code generator and another project may import this
  executable target and use it in its recipes in order to generate some source
  code.</p>

  <p>To support this semantics the <code>exe{}</code> target type has a
  peculiar default extension logic. Specifically, if the <code>exe{}</code>
  target is "output", then the extension is expected to be assigned by the
  matching rule according to the target platform for which this executable is
  built. But if it does not, then we fall back to no extension (for example, a
  script). If, however, the <code>exe{}</code> target is "input" (that is,
  it's listed as a prerequisite and there is no corresponding "output"
  target), then the extension of the host platform is used as the default.</p>

  <p>In all these cases the extension can also be specified explicitly. This,
  for example, would be necessary if the executable were a batch file:</p>

  <pre>h{generate}: exe{generate.bat}
{{
   diag $&lt; -> $>
   $&lt; -o $path($>)
}}</pre>

  <p>Here, without the explicit extension, the <code>.exe</code> extension
  would have been used by default.</p>

  <h1 id="variables">4 Variables</h1>

  <p><span class="note">This chapter is a work in progress and is
  incomplete.</span></p>

  <p>The following variable/value types can currently be used in
  <code>buildfiles</code>:</p>

  <pre>bool

int64
int64s

uint64
uint64s

string
strings
string_set
string_map

path
paths
dir_path
dir_paths

json
json_array
json_object
json_set
json_map

name
names
name_pair

cmdline
project_name
target_triplet</pre>

  <p>Note that while expansions in the target and prerequisite-specific
  assignments happen in the corresponding target and prerequisite contexts,
  respectively, for type/pattern-specific assignments they happen in the scope
  context. Plus, a type/pattern-specific prepend/append is applied at the time
  of expansion for the actual target. For example:</p>

  <pre>x = s

file{foo}:              # target
{
  x += t    # s t
  y = $x y  # s t y
}

file{foo}: file{bar}    # prerequisite
{
  x += p    # x t p
  y = $x y  # x t p y
}

file{b*}:               # type/pattern
{
  x += w   # &lt;append w>
  y = $x w # &lt;assign s w>
}

x = S

info $(file{bar}: x) # S w
info $(file{bar}: y) # s w</pre>

  <h1 id="functions">5 Functions</h1>

  <p><span class="note">This chapter is a work in progress and is
  incomplete.</span></p>

  <p>Functions in <code>build2</code> are organized into families, such as the
  <code>$string.*()</code> family for manipulating strings or
  <code>$regex.*()</code> for working with regular expressions. Most functions
  are pure and those that are not, such as <code>$builtin.getenv()</code>, are
  explicitly documented as such.</p>

  <p>Some functions, such as from the <code>$regex.*()</code> family, can only
  be called fully qualified with their family name. For example:</p>

  <pre>if $regex.match($name, '(.+)-(.+)')
  ...</pre>

  <p>While other functions can be called without explicit qualification. For
  example:</p>

  <pre>path = $getenv('PATH')</pre>

  <p>There are also functions that can be called unqualified only for certain
  types of arguments (this fact will be reflected in their synopsis and/or
  documentation). Note, however, that every function can always be called
  qualified.</p>

  <h2 id="functions-builtin">5.1 Builtin Functions</h2>

  <p>The <code>$builtin.*()</code> function family contains fundamental
  <code>build2</code> functions.</p>

  <h3 id="functions-builtin-defined">5.1.1
  <code>$builtin.defined()</code></h3>

  <pre>$defined(&lt;variable>)</pre>

  <p>Return true if the specified variable is defined in the calling scope or
  any outer scopes.</p>

  <p>Note that this function is not pure.</p>

  <h3 id="functions-builtin-visibility">5.1.2
  <code>$builtin.visibility()</code></h3>

  <pre>$visibility(&lt;variable>)</pre>

  <p>Return variable visibility if it is known and <code>null</code>
  otherwise.</p>

  <p>Possible visibility value are:</p>

  <pre>global  -- all outer scopes
project -- this project (no outer projects)
scope   -- this scope (no outer scopes)
target  -- target and target type/pattern-specific
prereq  -- prerequisite-specific</pre>

  <p>Note that this function is not pure.</p>

  <h3 id="functions-builtin-type">5.1.3 <code>$builtin.type()</code></h3>

  <pre>$type(&lt;value>)</pre>

  <p>Return the type name of the value or empty string if untyped.</p>

  <h3 id="functions-builtin-null">5.1.4 <code>$builtin.null()</code></h3>

  <pre>$null(&lt;value>)</pre>

  <p>Return true if the value is <code>null</code>.</p>

  <h3 id="functions-builtin-empty">5.1.5 <code>$builtin.empty()</code></h3>

  <pre>$empty(&lt;value>)</pre>

  <p>Return true if the value is empty.</p>

  <h3 id="functions-builtin-first">5.1.6 <code>$builtin.first()</code>,
  <code>$builtin.second()</code></h3>

  <pre>$first(&lt;value>[, &lt;not_pair>])
$second(&lt;value>[, &lt;not_pair>])</pre>

  <p>Return the first or the second half of a pair, respectively. If a value
  is not a pair, then return <code>null</code> unless the
  <code><i>not_pair</i></code> argument is <code>true</code>, in which case
  return the non-pair value.</p>

  <p>If multiple pairs are specified, then return the list of first/second
  halfs. If an element is not a pair, then omit it from the resulting list
  unless the <code><i>not_pair</i></code> argument is <code>true</code>, in
  which case add the non-pair element to the list.</p>

  <h3 id="functions-builtin-quote">5.1.7 <code>$builtin.quote()</code></h3>

  <pre>$quote(&lt;value>[, &lt;escape>])</pre>

  <p>Quote the value returning its string representation. If
  <code><i>escape</i></code> is <code>true</code>, then also escape (with a
  backslash) the quote characters being added (this is useful if the result
  will be re-parsed, for example as a script command line).</p>

  <h3 id="functions-builtin-getenv">5.1.8 <code>$builtin.getenv()</code></h3>

  <pre>$getenv(&lt;name>)</pre>

  <p>Get the value of the environment variable. Return <code>null</code> if
  the environment variable is not set.</p>

  <p>Note that if the build result can be affected by the variable being
  queried, then it should be reported with the <code>config.environment</code>
  directive.</p>

  <p>Note that this function is not pure.</p>

  <h2 id="functions-string">5.2 String Functions</h2>

  <h3 id="functions-string-icasecmp">5.2.1
  <code>$string.icasecmp()</code></h3>

  <pre>$string.icasecmp(&lt;untyped>, &lt;untyped>)
$icasecmp(&lt;string>, &lt;string>)</pre>

  <p>Compare ASCII strings ignoring case and returning the boolean value.</p>

  <h3 id="functions-string-contains">5.2.2
  <code>$string.contains()</code></h3>

  <pre>$string.contains(&lt;untyped>, &lt;untyped>[, &lt;flags>])
$contains(&lt;string>, &lt;string>[, &lt;flags>])</pre>

  <p>Check if the string (first argument) contains the given substring (second
  argument). The substring must not be empty.</p>

  <p>The following flags are supported:</p>

  <pre>icase  - compare ignoring case

once   - check if the substring occurs exactly once</pre>

  <p>See also <code>$string.starts_with()</code>,
  <code>$string.ends_with()</code>, <code>$regex.search()</code>.</p>

  <h3 id="functions-string-starts_with">5.2.3
  <code>$string.starts_with()</code></h3>

  <pre>$string.starts_with(&lt;untyped>, &lt;untyped>[, &lt;flags>])
$starts_with(&lt;string>, &lt;string>[, &lt;flags>])</pre>

  <p>Check if the string (first argument) begins with the given prefix (second
  argument). The prefix must not be empty.</p>

  <p>The following flags are supported:</p>

  <pre>icase  - compare ignoring case</pre>

  <p>See also <code>$string.contains()</code>.</p>

  <h3 id="functions-string-ends_with">5.2.4
  <code>$string.ends_with()</code></h3>

  <pre>$string.ends_with(&lt;untyped>, &lt;untyped>[, &lt;flags>])
$ends_with(&lt;string>, &lt;string>[, &lt;flags>])</pre>

  <p>Check if the string (first argument) ends with the given suffix (second
  argument). The suffix must not be empty.</p>

  <p>The following flags are supported:</p>

  <pre>icase  - compare ignoring case</pre>

  <p>See also <code>$string.contains()</code>.</p>

  <h3 id="functions-string-replace">5.2.5 <code>$string.replace()</code></h3>

  <pre>$string.replace(&lt;untyped>, &lt;from>, &lt;to> [, &lt;flags>])
$replace(&lt;string>, &lt;from>, &lt;to> [, &lt;flags>])</pre>

  <p>Replace occurences of substring <code><i>from</i></code> with
  <code><i>to</i></code> in a string. The <code><i>from</i></code> substring
  must not be empty.</p>

  <p>The following flags are supported:</p>

  <pre>icase       - compare ignoring case

first_only  - only replace the first match

last_only   - only replace the last match</pre>

  <p>If both <code>first_only</code> and <code>last_only</code> flags are
  specified, then <code><i>from</i></code> is replaced only if it occurs in
  the string once.</p>

  <p>See also <code>$regex.replace()</code>.</p>

  <h3 id="functions-string-trim">5.2.6 <code>$string.trim()</code></h3>

  <pre>$string.trim(&lt;untyped>)
$trim(&lt;string>)</pre>

  <p>Trim leading and trailing whitespaces in a string.</p>

  <h3 id="functions-string-lcase">5.2.7 <code>$string.lcase()</code>,
  <code>$string.ucase()</code></h3>

  <pre>$string.lcase(&lt;untyped>)
$string.ucase(&lt;untyped>)
$lcase(&lt;string>)
$ucase(&lt;string>)</pre>

  <p>Convert ASCII string into lower/upper case.</p>

  <h3 id="functions-string-size">5.2.8 <code>$string.size()</code></h3>

  <pre>$size(&lt;strings>)
$size(&lt;string-set>)
$size(&lt;string-map>)
$size(&lt;string>)</pre>

  <p>First three forms: return the number of elements in the sequence.</p>

  <p>Fourth form: return the number of characters (bytes) in the string.</p>

  <h3 id="functions-string-sort">5.2.9 <code>$string.sort()</code></h3>

  <pre>$sort(&lt;strings> [, &lt;flags>])</pre>

  <p>Sort strings in ascending order.</p>

  <p>The following flags are supported:</p>

  <pre>icase - sort ignoring case

dedup - in addition to sorting also remove duplicates</pre>

  <h3 id="functions-string-find">5.2.10 <code>$string.find()</code></h3>

  <pre>$find(&lt;strings>, &lt;string>[, &lt;flags>])</pre>

  <p>Return true if the string sequence contains the specified string.</p>

  <p>The following flags are supported:</p>

  <pre>icase - compare ignoring case</pre>

  <p>See also <code>$regex.find_match()</code> and
  <code>$regex.find_search()</code>.</p>

  <h3 id="functions-string-find_index">5.2.11
  <code>$string.find_index()</code></h3>

  <pre>$find_index(&lt;strings>, &lt;string>[, &lt;flags>])</pre>

  <p>Return the index of the first element in the string sequence that is
  equal to the specified string or <code>$size(strings)</code> if none is
  found.</p>

  <p>The following flags are supported:</p>

  <pre>icase - compare ignoring case</pre>

  <h3 id="functions-string-keys">5.2.12 <code>$string.keys()</code></h3>

  <pre>$keys(&lt;string-map>)</pre>

  <p>Return the list of keys in a string map.</p>

  <p>Note that the result is sorted in ascending order.</p>

  <h2 id="functions-integer">5.3 Integer Functions</h2>

  <h3 id="functions-integer-string">5.3.1 <code>$integer.string()</code></h3>

  <pre>$string(&lt;int64>)
$string(&lt;uint64>[, &lt;base>[, &lt;width>]])</pre>

  <p>Convert an integer to a string. For unsigned integers we can specify the
  desired base and width. For example:</p>

  <pre>x = [uint64] 0x0000ffff

c.poptions += "-DOFFSET=$x"                 # -DOFFSET=65535
c.poptions += "-DOFFSET=$string($x, 16)"    # -DOFFSET=0xffff
c.poptions += "-DOFFSET=$string($x, 16, 8)" # -DOFFSET=0x0000ffff</pre>

  <h3 id="functions-integer-integer_sequence">5.3.2
  <code>$integer.integer_sequence()</code></h3>

  <pre>$integer_sequence(&lt;begin>, &lt;end>[, &lt;step>])</pre>

  <p>Return the list of uint64 integers starting from
  <code><i>begin</i></code> (including) to <code><i>end</i></code> (excluding)
  with the specified <code><i>step</i></code> or <code>1</code> if
  unspecified. If <code><i>begin</i></code> is greater than
  <code><i>end</i></code>, empty list is returned.</p>

  <h3 id="functions-integer-size">5.3.3 <code>$integer.size()</code></h3>

  <pre>$size(&lt;ints>)</pre>

  <p>Return the number of elements in the sequence.</p>

  <h3 id="functions-integer-sort">5.3.4 <code>$integer.sort()</code></h3>

  <pre>$sort(&lt;ints> [, &lt;flags>])</pre>

  <p>Sort integers in ascending order.</p>

  <p>The following flags are supported:</p>

  <pre>dedup - in addition to sorting also remove duplicates</pre>

  <h3 id="functions-integer-find">5.3.5 <code>$integer.find()</code></h3>

  <pre>$find(&lt;ints>, &lt;int>)</pre>

  <p>Return true if the integer sequence contains the specified integer.</p>

  <h3 id="functions-integer-find_index">5.3.6
  <code>$integer.find_index()</code></h3>

  <pre>$find_index(&lt;ints>, &lt;int>)</pre>

  <p>Return the index of the first element in the integer sequence that is
  equal to the specified integer or <code>$size(ints)</code> if none is
  found.</p>

  <h2 id="functions-bool">5.4 Bool Functions</h2>

  <h3 id="functions-bool-string">5.4.1 <code>$bool.string()</code></h3>

  <pre>$string(&lt;bool>)</pre>

  <p>Convert a boolean value to a string literal <code>true</code> or
  <code>false</code>.</p>

  <h2 id="functions-path">5.5 Path Functions</h2>

  <p>The <code>$path.*()</code> function family contains function that
  manipulating filesystem paths.</p>

  <h3 id="functions-path-string">5.5.1 <code>$path.string()</code></h3>

  <pre>$string(&lt;paths>)</pre>

  <p>Return the traditional string representation of a path (or a list of
  string representations for a list of paths). In particular, for directory
  paths, the traditional representation does not include the trailing
  directory separator (except for the POSIX root directory). See
  <code>$representation()</code> below for the precise string
  representation.</p>

  <h3 id="functions-path-posix_string">5.5.2
  <code>$path.posix_string()</code></h3>

  <pre>$posix_string(&lt;paths>)
$path.posix_string(&lt;untyped>)</pre>

  <p>Return the traditional string representation of a path (or a list of
  string representations for a list of paths) using the POSIX directory
  separators (forward slashes).</p>

  <h3 id="functions-path-representation">5.5.3
  <code>$path.representation()</code></h3>

  <pre>$representation(&lt;paths>)</pre>

  <p>Return the precise string representation of a path (or a list of string
  representations for a list of paths). In particular, for directory paths,
  the precise representation includes the trailing directory separator. See
  <code>$string()</code> above for the traditional string representation.</p>

  <h3 id="functions-path-posix_representation">5.5.4
  <code>$path.posix_representation()</code></h3>

  <pre>$posix_representation(&lt;paths>)
$path.posix_representation(&lt;untyped>)</pre>

  <p>Return the precise string representation of a path (or a list of string
  representations for a list of paths) using the POSIX directory separators
  (forward slashes).</p>

  <h3 id="functions-path-absolute">5.5.5 <code>$path.absolute()</code></h3>

  <pre>$absolute(&lt;path>)
$path.absolute(&lt;untyped>)</pre>

  <p>Return true if the path is absolute and false otherwise.</p>

  <h3 id="functions-path-simple">5.5.6 <code>$path.simple()</code></h3>

  <pre>$simple(&lt;path>)
$path.simple(&lt;untyped>)</pre>

  <p>Return true if the path is simple, that is, has no direcrory component,
  and false otherwise.</p>

  <p>Note that on POSIX <code>/foo</code> is not a simple path (it is
  <code>foo</code> in the root directory) while <code>/</code> is (it is the
  root directory).</p>

  <h3 id="functions-path-sub_path">5.5.7 <code>$path.sub_path()</code></h3>

  <pre>$sub_path(&lt;path>, &lt;path>)
$path.sub_path(&lt;untyped>, &lt;untyped>)</pre>

  <p>Return true if the path specified as the first argument is a sub-path of
  the one specified as the second argument (in other words, the second
  argument is a prefix of the first) and false otherwise. Both paths are
  expected to be normalized. Note that this function returns true if the paths
  are equal. Empty path is considered a prefix of any path.</p>

  <h3 id="functions-path-super_path">5.5.8
  <code>$path.super_path()</code></h3>

  <pre>$super_path(&lt;path>, &lt;path>)
$path.super_path(&lt;untyped>, &lt;untyped>)</pre>

  <p>Return true if the path specified as the first argument is a super-path
  of the one specified as the second argument (in other words, the second
  argument is a suffix of the first) and false otherwise. Both paths are
  expected to be normalized. Note that this function returns true if the paths
  are equal. Empty path is considered a suffix of any path.</p>

  <h3 id="functions-path-directory">5.5.9 <code>$path.directory()</code></h3>

  <pre>$directory(&lt;paths>)
$path.directory(&lt;untyped>)</pre>

  <p>Return the directory part of a path (or a list of directory parts for a
  list of paths) or an empty path if there is no directory. A directory of a
  root directory is an empty path.</p>

  <h3 id="functions-path-root_directory">5.5.10
  <code>$path.root_directory()</code></h3>

  <pre>$root_directory(&lt;paths>)
$path.root_directory(&lt;untyped>)</pre>

  <p>Return the root directory of a path (or a list of root directories for a
  list of paths) or an empty path if the specified path is not absolute.</p>

  <h3 id="functions-path-leaf">5.5.11 <code>$path.leaf()</code></h3>

  <pre>$leaf(&lt;paths>)
$path.leaf(&lt;untyped>)
$leaf(&lt;paths>, &lt;dir-path>)
$path.leaf(&lt;untyped>, &lt;dir-path>)</pre>

  <p>First form (one argument): return the last component of a path (or a list
  of last components for a list of paths).</p>

  <p>Second form (two arguments): return a path without the specified
  directory part (or a list of paths without the directory part for a list of
  paths). Return an empty path if the paths are the same. Issue diagnostics
  and fail if the directory is not a prefix of the path. Note: expects both
  paths to be normalized.</p>

  <h3 id="functions-path-relative">5.5.12 <code>$path.relative()</code></h3>

  <pre>$relative(&lt;paths>, &lt;dir-path>)
$path.relative(&lt;untyped>, &lt;dir-path>)</pre>

  <p>Return the path relative to the specified directory that is equivalent to
  the specified path (or a list of relative paths for a list of specified
  paths). Issue diagnostics and fail if a relative path cannot be derived (for
  example, paths are on different drives on Windows).</p>

  <p>Note: to check if a path if relative, use
  <code>$path.absolute()</code>.</p>

  <h3 id="functions-path-base">5.5.13 <code>$path.base()</code></h3>

  <pre>$base(&lt;paths>)
$path.base(&lt;untyped>)</pre>

  <p>Return the base part (without the extension) of a path (or a list of base
  parts for a list of paths).</p>

  <h3 id="functions-path-extension">5.5.14 <code>$path.extension()</code></h3>

  <pre>$extension(&lt;path>)
$path.extension(&lt;untyped>)</pre>

  <p>Return the extension part (without the dot) of a path or empty string if
  there is no extension.</p>

  <h3 id="functions-path-complete">5.5.15 <code>$path.complete()</code></h3>

  <pre>$complete(&lt;paths>)
$path.complete(&lt;untyped>)</pre>

  <p>Complete the path (or list of paths) by prepending the current working
  directory unless the path is already absolute.</p>

  <h3 id="functions-path-canonicalize">5.5.16
  <code>$path.canonicalize()</code></h3>

  <pre>$canonicalize(&lt;paths>)
$path.canonicalize(&lt;untyped>)</pre>

  <p>Canonicalize the path (or list of paths) by converting all the directory
  separators to the canonical form for the host platform. Note that multiple
  directory separators are not collapsed.</p>

  <h3 id="functions-path-normalize">5.5.17 <code>$path.normalize()</code>,
  <code>$path.try_normalize()</code></h3>

  <pre>$normalize(&lt;paths>)
$path.normalize(&lt;untyped>)
$try_normalize(&lt;path>)
$path.try_normalize(&lt;untyped>)</pre>

  <p>Normalize the path (or list of paths) by collapsing the <code>.</code>
  and <code>..</code> components if possible, collapsing multiple directory
  separators, and converting all the directory separators to the canonical
  form for the host platform.</p>

  <p>If the resulting path would be invalid, the <code>$normalize()</code>
  version issues diagnostics and fails while the <code>$try_normalize()</code>
  version returns <code>null</code>. Note that <code>$try_normalize()</code>
  only accepts a single path.</p>

  <h3 id="functions-path-actualize">5.5.18 <code>$path.actualize()</code>,
  <code>$path.try_actualize()</code></h3>

  <pre>$actualize(&lt;paths>)
$path.actualize(&lt;untyped>)
$try_actualize(&lt;path>)
$path.try_actualize(&lt;untyped>)</pre>

  <p>Actualize the path (or list of paths) by first normalizing it and then
  for host platforms with case-insensitive filesystems obtaining the actual
  spelling of the path.</p>

  <p>Only an absolute path can be actualized. If a path component does not
  exist, then its (and all subsequent) spelling is unchanged. Note that this
  is a potentially expensive operation.</p>

  <p>If the resulting path would be invalid or in case of filesystem errors
  (other than non-existent component), the <code>$actualize()</code> version
  issues diagnostics and fails while the <code>$try_actualize()</code> version
  returns <code>null</code>. Note that <code>$try_actualize()</code> only
  accepts a single path.</p>

  <p>Note that this function is not pure.</p>

  <h3 id="functions-path-size">5.5.19 <code>$path.size()</code></h3>

  <pre>$size(&lt;paths>)
$size(&lt;path>)</pre>

  <p>First form: return the number of elements in the paths sequence.</p>

  <p>Second form: return the number of characters (bytes) in the path. Note
  that for <code>dir_path</code> the result does not include the trailing
  directory separator (except for the POSIX root directory).</p>

  <h3 id="functions-path-sort">5.5.20 <code>$path.sort()</code></h3>

  <pre>$sort(&lt;paths>[, &lt;flags>])</pre>

  <p>Sort paths in ascending order. Note that on host platforms with a
  case-insensitive filesystem the order is case-insensitive.</p>

  <p>The following flags are supported:</p>

  <pre>dedup - in addition to sorting also remove duplicates</pre>

  <h3 id="functions-path-find">5.5.21 <code>$path.find()</code></h3>

  <pre>$find(&lt;paths>, &lt;path>)</pre>

  <p>Return true if the paths sequence contains the specified path. Note that
  on host platforms with a case-insensitive filesystem the comparison is
  case-insensitive.</p>

  <h3 id="functions-path-find_index">5.5.22
  <code>$path.find_index()</code></h3>

  <pre>$find_index(&lt;paths>, &lt;path>)</pre>

  <p>Return the index of the first element in the paths sequence that is equal
  to the specified path or <code>$size(paths)</code> if none is found. Note
  that on host platforms with a case-insensitive filesystem the comparison is
  case-insensitive.</p>

  <h3 id="functions-path-match">5.5.23 <code>$path.match()</code></h3>

  <pre>$path.match(&lt;entry>, &lt;pattern>[, &lt;start-dir>])</pre>

  <p>Match a filesystem entry name against a name pattern (both are strings),
  or a filesystem entry path against a path pattern. For the latter case the
  start directory may also be required (see below). The pattern is a
  shell-like wildcard pattern. The semantics of the
  <code><i>pattern</i></code> and <code><i>entry</i></code> arguments is
  determined according to the following rules:</p>

  <p>1. The arguments must be of the string or path types, or be untyped.</p>

  <p>2. If one of the arguments is typed, then the other one must be of the
  same type or be untyped. In the later case, an untyped argument is converted
  to the type of the other argument.</p>

  <p>3. If both arguments are untyped and the start directory is specified,
  then the arguments are converted to the path type.</p>

  <p>4. If both arguments are untyped and the start directory is not
  specified, then, if one of the arguments is syntactically a path (the value
  contains a directory separator), then they are converted to the path type,
  otherwise -- to the string type (match as names).</p>

  <p>If pattern and entry paths are both either absolute or relative and not
  empty, and the first pattern component is not a self-matching wildcard
  (doesn't contain <code>***</code>), then the start directory is not
  required, and is ignored if specified. Otherwise, the start directory must
  be specified and be an absolute path.</p>

  <h2 id="functions-name">5.6 Name Functions</h2>

  <p>The <code>$name.*()</code> function family contains function that operate
  on target and prerequisite names. See also the <a
  href="#functions-target"><code>$target.*()</code> function family</a> for
  functions that operate on actual targets.</p>

  <h3 id="functions-name-name">5.6.1 <code>$name.name()</code></h3>

  <pre>$name(&lt;names>)</pre>

  <p>Return the name of a target (or a list of names for a list of
  targets).</p>

  <h3 id="functions-name-extension">5.6.2 <code>$name.extension()</code></h3>

  <pre>$extension(&lt;name>)</pre>

  <p>Return the extension of a target.</p>

  <p>Note that this function returns <code>null</code> if the extension is
  unspecified (default) and empty string if it's specified as no
  extension.</p>

  <h3 id="functions-name-directory">5.6.3 <code>$name.directory()</code></h3>

  <pre>$directory(&lt;names>)</pre>

  <p>Return the directory of a target (or a list of directories for a list of
  targets).</p>

  <h3 id="functions-name-target_type">5.6.4
  <code>$name.target_type()</code></h3>

  <pre>$target_type(&lt;names>)</pre>

  <p>Return the target type name of a target (or a list of target type names
  for a list of targets).</p>

  <h3 id="functions-name-project">5.6.5 <code>$name.project()</code></h3>

  <pre>$project(&lt;name>)</pre>

  <p>Return the project of a target or <code>null</code> if not
  project-qualified.</p>

  <h3 id="functions-name-is_a">5.6.6 <code>$name.is_a()</code></h3>

  <pre>$is_a(&lt;name>, &lt;target-type>)</pre>

  <p>Return true if the <code><i>name</i></code>'s target type is-a
  <code><i>target-type</i></code>. Note that this is a dynamic type check that
  takes into account target type inheritance.</p>

  <h3 id="functions-name-filter">5.6.7 <code>$name.filter()</code>,
  <code>$name.filter_out()</code></h3>

  <pre>$filter(&lt;names>, &lt;target-types>)
$filter_out(&lt;names>, &lt;target-types>)</pre>

  <p>Return names with target types which are-a (<code>filter</code>) or not
  are-a (<code>filter_out</code>) one of <code><i>target-types</i></code>. See
  <code>$is_a()</code> for background.</p>

  <h3 id="functions-name-size">5.6.8 <code>$name.size()</code></h3>

  <pre>$size(&lt;names>)</pre>

  <p>Return the number of elements in the sequence.</p>

  <h3 id="functions-name-sort">5.6.9 <code>$name.sort()</code></h3>

  <pre>$sort(&lt;names>[, &lt;flags>])</pre>

  <p>Sort names in ascending order.</p>

  <p>The following flags are supported:</p>

  <pre>dedup - in addition to sorting also remove duplicates</pre>

  <h3 id="functions-name-find">5.6.10 <code>$name.find()</code></h3>

  <pre>$find(&lt;names>, &lt;name>)</pre>

  <p>Return true if the name sequence contains the specified name.</p>

  <h3 id="functions-name-find_index">5.6.11
  <code>$name.find_index()</code></h3>

  <pre>$find_index(&lt;names>, &lt;name>)</pre>

  <p>Return the index of the first element in the name sequence that is equal
  to the specified name or <code>$size(names)</code> if none is found.</p>

  <h2 id="functions-target">5.7 Target Functions</h2>

  <p>The <code>$target.*()</code> function family contains function that
  operate on targets. See also the <a
  href="#functions-name"><code>$name.*()</code> function family</a> for
  functions that operate on target (and prerequisite) names.</p>

  <h3 id="functions-target-path">5.7.1 <code>$target.path()</code></h3>

  <pre>$path(&lt;names>)</pre>

  <p>Return the path of a target (or a list of paths for a list of targets).
  The path must be assigned, which normally happens during match. As a result,
  this function is normally called form a recipe.</p>

  <p>Note that while this function is technically not pure, we don't mark it
  as such since it can only be called (normally form a recipe) after the
  target has been matched, meaning that this target is a prerequisite and
  therefore this impurity has been accounted for.</p>

  <h3 id="functions-target-process_path">5.7.2
  <code>$target.process_path()</code></h3>

  <pre>$process_path(&lt;name>)</pre>

  <p>Return the process path of an executable target.</p>

  <p>Note that while this function is not technically pure, we don't mark it
  as such for the same reasons as for <code>$path()</code> above.</p>

  <h2 id="functions-regex">5.8 Regex Functions</h2>

  <p>The <code>$regex.*()</code> function family contains function that
  provide comprehensive regular expression matching and substitution
  facilities. The supported regular expression flavor is ECMAScript (more
  specifically, ECMA-262-based C++11 regular expressions).</p>

  <p>In the <code>$regex.*()</code> functions the substitution escape
  sequences in the format string (the <code><i>fmt</i></code> argument) are
  extended with a subset of the Perl escape sequences: <code>\n</code>,
  <code>\u</code>, <code>\l</code>, <code>\U</code>, <code>\L</code>,
  <code>\E</code>, <code>\1</code> ... <code>\9</code>, and <code>\\</code>.
  Note that the standard ECMAScript escape sequences (<code>$1</code>,
  <code>$2</code>, <code>$&amp;</code>, etc) are still supported.</p>

  <p>Note that functions from the <code>$regex.*()</code> family can only be
  called fully qualified with their family name. For example:</p>

  <pre>if $regex.match($name, '(.+)-(.+)')
  ...</pre>

  <h3 id="functions-regex-match">5.8.1 <code>$regex.match()</code></h3>

  <pre>$regex.match(&lt;val>, &lt;pat> [, &lt;flags>])</pre>

  <p>Match a value of an arbitrary type against the regular expression.
  Convert the value to string prior to matching. Return the boolean value
  unless <code>return_subs</code> flag is specified (see below), in which case
  return names (or <code>null</code> if no match).</p>

  <p>The following flags are supported:</p>

  <pre>icase       - match ignoring case

return_subs - return names (rather than boolean), that contain
              sub-strings that match the marked sub-expressions
              and null if no match</pre>

  <h3 id="functions-regex-find_match">5.8.2
  <code>$regex.find_match()</code></h3>

  <pre>$regex.find_match(&lt;vals>, &lt;pat> [, &lt;flags>])</pre>

  <p>Match list elements against the regular expression and return true if the
  match is found. Convert the elements to strings prior to matching.</p>

  <p>The following flags are supported:</p>

  <pre>icase - match ignoring case</pre>

  <h3 id="functions-regex-filter_match">5.8.3
  <code>$regex.filter_match()</code>,
  <code>$regex.filter_out_match()</code></h3>

  <pre>$regex.filter_match(&lt;vals>, &lt;pat> [, &lt;flags>])
$regex.filter_out_match(&lt;vals>, &lt;pat> [, &lt;flags>])</pre>

  <p>Return elements of a list that match (<code>filter</code>) or do not
  match (<code>filter_out</code>) the regular expression. Convert the elements
  to strings prior to matching.</p>

  <p>The following flags are supported:</p>

  <pre>icase - match ignoring case</pre>

  <h3 id="functions-regex-search">5.8.4 <code>$regex.search()</code></h3>

  <pre>$regex.search(&lt;val>, &lt;pat> [, &lt;flags>])</pre>

  <p>Determine if there is a match between the regular expression and some
  part of a value of an arbitrary type. Convert the value to string prior to
  searching. Return the boolean value unless <code>return_match</code> or
  <code>return_subs</code> flag is specified (see below) in which case return
  names (<code>null</code> if no match).</p>

  <p>The following flags are supported:</p>

  <pre>icase        - match ignoring case

return_match - return names (rather than boolean), that contain a
               sub-string that matches the whole regular expression
               and null if no match

return_subs  - return names (rather than boolean), that contain
               sub-strings that match the marked sub-expressions
               and null if no match</pre>

  <p>If both <code>return_match</code> and <code>return_subs</code> flags are
  specified then the sub-string that matches the whole regular expression
  comes first.</p>

  <p>See also <code>$string.contains()</code>,
  <code>$string.starts_with()</code>, <code>$string.ends_with()</code>.</p>

  <h3 id="functions-regex-find_search">5.8.5
  <code>$regex.find_search()</code></h3>

  <pre>$regex.find_search(&lt;vals>, &lt;pat> [, &lt;flags>])</pre>

  <p>Determine if there is a match between the regular expression and some
  part of any of the list elements. Convert the elements to strings prior to
  matching.</p>

  <p>The following flags are supported:</p>

  <pre>icase - match ignoring case</pre>

  <h3 id="functions-regex-filter_search">5.8.6
  <code>$regex.filter_search()</code>,
  <code>$regex.filter_out_search()</code></h3>

  <pre>$regex.filter_search(&lt;vals>, &lt;pat> [, &lt;flags>])
$regex.filter_out_search(&lt;vals>, &lt;pat> [, &lt;flags>])</pre>

  <p>Return elements of a list for which there is a match
  (<code>filter</code>) or no match (<code>filter_out</code>) between the
  regular expression and some part of the element. Convert the elements to
  strings prior to matching.</p>

  <p>The following flags are supported:</p>

  <pre>icase - match ignoring case</pre>

  <h3 id="functions-regex-replace">5.8.7 <code>$regex.replace()</code></h3>

  <pre>$regex.replace(&lt;val>, &lt;pat>, &lt;fmt> [, &lt;flags>])</pre>

  <p>Replace matched parts in a value of an arbitrary type, using the format
  string. Convert the value to string prior to matching. The result value is
  always untyped, regardless of the argument type.</p>

  <p>The following flags are supported:</p>

  <pre>icase             - match ignoring case

format_first_only - only replace the first match

format_no_copy    - do not copy unmatched value parts into the
                    result</pre>

  <p>If both <code>format_first_only</code> and <code>format_no_copy</code>
  flags are specified then the result will only contain the replacement of the
  first match.</p>

  <p>See also <code>$string.replace()</code>.</p>

  <h3 id="functions-regex-replace_lines">5.8.8
  <code>$regex.replace_lines()</code></h3>

  <pre>$regex.replace_lines(&lt;val>, &lt;pat>, &lt;fmt> [, &lt;flags>])</pre>

  <p>Convert the value to string, parse it into lines and for each line apply
  the <code>$regex.replace()</code> function with the specified pattern,
  format, and flags. If the format argument is <code>null</code>, omit the
  "all-<code>null</code>" replacements for the matched lines from the result.
  Return unmatched lines and line replacements as a <code>name</code> list
  unless <code>return_lines</code> flag is specified (see below), in which
  case return a single multi-line simple <code>name</code> value.</p>

  <p>The following flags are supported in addition to the
  <code>$regex.replace()</code> function's flags:</p>

  <pre>return_lines - return the simple name (rather than a name list)
               containing the unmatched lines and line replacements
               separated with newlines.</pre>

  <p>Note that if <code>format_no_copy</code> is specified, unmatched lines
  are not copied either.</p>

  <h3 id="functions-regex-split">5.8.9 <code>$regex.split()</code></h3>

  <pre>$regex.split(&lt;val>, &lt;pat>, &lt;fmt> [, &lt;flags>])</pre>

  <p>Split a value of an arbitrary type into a list of unmatched value parts
  and replacements of the matched parts, omitting empty ones (unless the
  <code>format_copy_empty</code> flag is specified). Convert the value to
  string prior to matching.</p>

  <p>The following flags are supported:</p>

  <pre>icase             - match ignoring case

format_no_copy    - do not copy unmatched value parts into the
                    result

format_copy_empty - copy empty elements into the result</pre>

  <h3 id="functions-regex-merge">5.8.10 <code>$regex.merge()</code></h3>

  <pre>$regex.merge(&lt;vals>, &lt;pat>, &lt;fmt> [, &lt;delim> [, &lt;flags>]])</pre>

  <p>Replace matched parts in a list of elements using the regex format
  string. Convert the elements to strings prior to matching. The result value
  is untyped and contains concatenation of transformed non-empty elements
  (unless the <code>format_copy_empty</code> flag is specified) optionally
  separated with a delimiter.</p>

  <p>The following flags are supported:</p>

  <pre>icase             - match ignoring case

format_first_only - only replace the first match

format_no_copy    - do not copy unmatched value parts into the
                    result

format_copy_empty - copy empty elements into the result</pre>

  <p>If both <code>format_first_only</code> and <code>format_no_copy</code>
  flags are specified then the result will be a concatenation of only the
  first match replacements.</p>

  <h3 id="functions-regex-apply">5.8.11 <code>$regex.apply()</code></h3>

  <pre>$regex.apply(&lt;vals>, &lt;pat>, &lt;fmt> [, &lt;flags>])</pre>

  <p>Replace matched parts of each element in a list using the regex format
  string. Convert the elements to strings prior to matching. Return a list of
  transformed elements, omitting the empty ones (unless the
  <code>format_copy_empty</code> flag is specified).</p>

  <p>The following flags are supported:</p>

  <pre>icase             - match ignoring case

format_first_only - only replace the first match

format_no_copy    - do not copy unmatched value parts into the
                    result

format_copy_empty - copy empty elements into the result</pre>

  <p>If both <code>format_first_only</code> and <code>format_no_copy</code>
  flags are specified then the result elements will only contain the
  replacement of the first match.</p>

  <h2 id="functions-json">5.9 JSON Functions</h2>

  <p>The <code>$json.*()</code> function family contains function that operate
  on the JSON types: <code>json</code>, <code>json_array</code>, and
  <code>json_object</code>. For example:</p>

  <pre>j = [json] one@1 two@abc three@([json] x@1 y@-1)

for m: $j
{
  n = $member_name($m)
  v = $member_value($m)

  info $n $value_type($v) $v
}</pre>

  <h3 id="functions-json-value_type">5.9.1
  <code>$json.value_type()</code></h3>

  <pre>$value_type(&lt;json>[, &lt;distinguish_numbers>])</pre>

  <p>Return the type of a JSON value: <code>null</code>, <code>boolean</code>,
  <code>number</code>, <code>string</code>, <code>array</code>, or
  <code>object</code>. If the <code><i>distinguish_numbers</i></code> argument
  is <code>true</code>, then instead of <code>number</code> return
  <code>signed number</code>, <code>unsigned number</code>, or
  <code>hexadecimal number</code>.</p>

  <h3 id="functions-json-value_size">5.9.2
  <code>$json.value_size()</code></h3>

  <pre>$value_size(&lt;json>)</pre>

  <p>Return the size of a JSON value.</p>

  <p>The size of a <code>null</code> value is <code>0</code>. The sizes of
  simple values (<code>boolean</code>, <code>number</code>, and
  <code>string</code>) is <code>1</code>. The size of <code>array</code> and
  <code>object</code> values is the number of elements and members,
  respectively.</p>

  <p>Note that the size of a <code>string</code> JSON value is not the length
  of the string. To get the length call <code>$string.size()</code> instead by
  casting the JSON value to the <code>string</code> value type.</p>

  <h3 id="functions-json-member_name">5.9.3
  <code>$json.member_name()</code></h3>

  <pre>$member_name(&lt;json-member>)</pre>

  <p>Return the name of a JSON object member.</p>

  <h3 id="functions-json-member_value">5.9.4
  <code>$json.member_value()</code></h3>

  <pre>$member_value(&lt;json-member>)</pre>

  <p>Return the value of a JSON object member.</p>

  <h3 id="functions-json-object_names">5.9.5
  <code>$json.object_names()</code></h3>

  <pre>$object_names(&lt;json-object>)</pre>

  <p>Return the list of names in the JSON object. If the JSON
  <code>null</code> is passed instead, assume it is a missing object and
  return an empty list.</p>

  <h3 id="functions-json-array_size">5.9.6
  <code>$json.array_size()</code></h3>

  <pre>$array_size(&lt;json-array>)</pre>

  <p>Return the number of elements in the JSON array. If the JSON
  <code>null</code> value is passed instead, assume it is a missing array and
  return <code>0</code>.</p>

  <h3 id="functions-json-array_find">5.9.7
  <code>$json.array_find()</code></h3>

  <pre>$array_find(&lt;json-array>, &lt;json>)</pre>

  <p>Return true if the JSON array contains the specified JSON value. If the
  JSON <code>null</code> value is passed instead, assume it is a missing array
  and return <code>false</code>.</p>

  <h3 id="functions-json-array_find_index">5.9.8
  <code>$json.array_find_index()</code></h3>

  <pre>$array_find_index(&lt;json-array>, &lt;json>)</pre>

  <p>Return the index of the first element in the JSON array that is equal to
  the specified JSON value or
  <code>$array_size(<code><i>json-array</i></code>)</code> if none is found.
  If the JSON <code>null</code> value is passed instead, assume it is a
  missing array and return <code>0</code>.</p>

  <h3 id="functions-json-load">5.9.9 <code>$json.load()</code></h3>

  <pre>$json.load(&lt;path>)</pre>

  <p>Parse the contents of the specified file as JSON input text and return
  the result as a value of the <code>json</code> type.</p>

  <p>See also <code>$json.parse()</code>.</p>

  <p>Note that this function is not pure.</p>

  <h3 id="functions-json-parse">5.9.10 <code>$json.parse()</code></h3>

  <pre>$json.parse(&lt;text>)</pre>

  <p>Parse the specified JSON input text and return the result as a value of
  the <code>json</code> type.</p>

  <p>See also <code>$json.load()</code> and
  <code>$json.serialize()</code>.</p>

  <h3 id="functions-json-serialize">5.9.11 <code>$json.serialize()</code></h3>

  <pre>$serialize(&lt;json>[, &lt;indentation>])</pre>

  <p>Serialize the specified JSON value and return the resulting JSON output
  text.</p>

  <p>The optional <code><i>indentation</i></code> argument specifies the
  number of indentation spaces that should be used for pretty-printing. If
  <code>0</code> is passed, then no pretty-printing is performed. The default
  is <code>2</code> spaces.</p>

  <p>See also <code>$json.parse()</code>.</p>

  <h3 id="functions-json-size">5.9.12 <code>$json.size()</code></h3>

  <pre>$size(&lt;json-set>)
$size(&lt;json-map>)</pre>

  <p>Return the number of elements in the sequence.</p>

  <h3 id="functions-json-keys">5.9.13 <code>$json.keys()</code></h3>

  <pre>$keys(&lt;json-map>)</pre>

  <p>Return the list of keys in a json map as a json array.</p>

  <p>Note that the result is sorted in ascending order.</p>

  <h2 id="functions-process">5.10 Process Functions</h2>

  <h3 id="functions-process-run">5.10.1 <code>$process.run()</code></h3>

  <pre>$process.run(&lt;prog>[ &lt;args>...])</pre>

  <p>Run builtin or external program and return trimmed <code>stdout</code>
  output.</p>

  <p>Note that if the result of executing the program can be affected by
  environment variables and this result can in turn affect the build result,
  then such variables should be reported with the
  <code>config.environment</code> directive.</p>

  <p>Note that this function is not pure and can only be called during the
  load phase.</p>

  <h3 id="functions-process-run_regex">5.10.2
  <code>$process.run_regex()</code></h3>

  <pre>$process.run_regex(&lt;prog>[ &lt;args>...], &lt;pat>[, &lt;fmt>])</pre>

  <p>Run builtin or external program and return <code>stdout</code> output
  lines matched and optionally processed with a regular expression.</p>

  <p>Each line of stdout (including the customary trailing blank) is matched
  (as a whole) against <code><i>pat</i></code> and, if successful, returned,
  optionally processed with <code><i>fmt</i></code>, as an element of a list.
  See the <code>$regex.*()</code> function family for details on regular
  expressions and format strings.</p>

  <p>Note that if the result of executing the program can be affected by
  environment variables and this result can in turn affect the build result,
  then such variables should be reported with the
  <code>config.environment</code> directive.</p>

  <p>Note that this function is not pure and can only be called during the
  load phase.</p>

  <h2 id="functions-filesystem">5.11 Filesystem Functions</h2>

  <h3 id="functions-filesystem-file_exists">5.11.1
  <code>$filesystem.file_exists()</code></h3>

  <pre>$file_exists(&lt;path>)</pre>

  <p>Return true if a filesystem entry at the specified path exists and is a
  regular file (or is a symlink to a regular file) and false otherwise.</p>

  <p>Note that this function is not pure.</p>

  <h3 id="functions-filesystem-directory_exists">5.11.2
  <code>$filesystem.directory_exists()</code></h3>

  <pre>$directory_exists(&lt;path>)</pre>

  <p>Return true if a filesystem entry at the specified path exists and is a
  directory (or is a symlink to a directory) and false otherwise.</p>

  <p>Note that this function is not pure.</p>

  <h3 id="functions-filesystem-path_search">5.11.3
  <code>$filesystem.path_search()</code></h3>

  <pre>$path_search(&lt;pattern>[, &lt;start-dir>])</pre>

  <p>Return filesystem paths that match the shell-like wildcard pattern. If
  the pattern is an absolute path, then the start directory is ignored (if
  present). Otherwise, the start directory must be specified and be
  absolute.</p>

  <p>Note that this function is not pure.</p>

  <h2 id="functions-project_name">5.12 Project Name Functions</h2>

  <p>The <code>$project_name.*()</code> function family contains function that
  operate on the <code>project_name</code> type.</p>

  <h3 id="functions-project_name-string">5.12.1
  <code>$project_name.string()</code></h3>

  <pre>$string(&lt;project-name>)</pre>

  <p>Return the string representation of a project name. See also the
  <code>$variable()</code> function below.</p>

  <h3 id="functions-project_name-base">5.12.2
  <code>$project_name.base()</code></h3>

  <pre>$base(&lt;project-name>[, &lt;extension>])</pre>

  <p>Return the base part (without the extension) of a project name.</p>

  <p>If <code><i>extension</i></code> is specified, then only remove that
  extension. Note that <code><i>extension</i></code> should not include the
  dot and the comparison is always case-insensitive.</p>

  <h3 id="functions-project_name-extension">5.12.3
  <code>$project_name.extension()</code></h3>

  <pre>$extension(&lt;project-name>)</pre>

  <p>Return the extension part (without the dot) of a project name or empty
  string if there is no extension.</p>

  <h3 id="functions-project_name-variable">5.12.4
  <code>$project_name.variable()</code></h3>

  <pre>$variable(&lt;project-name>)</pre>

  <p>Return the string representation of a project name that is sanitized to
  be usable as a variable name. Specifically, <code>.</code>, <code>-</code>,
  and <code>+</code> are replaced with <code>_</code>.</p>

  <h2 id="functions-process-path">5.13 Process Path Functions</h2>

  <p>The <code>$process_path.*()</code> function family contains function that
  operate on the <code>process_path</code> type and its extended
  <code>process_path_ex</code> variant. These types describe a path to an
  executable that, if necessary, has been found in <code>PATH</code>,
  completed with an extension, etc. The <code>process_path_ex</code> variant
  includes additional metadata, such as the stable process name for
  diagnostics and the executable checksum for change tracking.</p>

  <h3 id="functions-process_path-recall">5.13.1
  <code>$process_path.recall()</code></h3>

  <pre>$recall(&lt;process-path>)</pre>

  <p>Return the recall path of an executable, that is, a path that is not
  necessarily absolute but which nevertheless can be used to re-run the
  executable in the current environment. This path, for example, could be used
  in diagnostics when printing the failing command line.</p>

  <h3 id="functions-process_path-effect">5.13.2
  <code>$process_path.effect()</code></h3>

  <pre>$effect(&lt;process-path>)</pre>

  <p>Return the effective path of an executable, that is, the absolute path to
  the executable that will also include any omitted extensions, etc.</p>

  <h3 id="functions-process_path-name">5.13.3
  <code>$process_path.name()</code></h3>

  <pre>$name(&lt;process-path-ex>)</pre>

  <p>Return the stable process name for diagnostics.</p>

  <h3 id="functions-process_path-checksum">5.13.4
  <code>$process_path.checksum()</code></h3>

  <pre>$checksum(&lt;process-path-ex>)</pre>

  <p>Return the executable checksum for change tracking.</p>

  <h3 id="functions-process_path-env_checksum">5.13.5
  <code>$process_path.env_checksum()</code></h3>

  <pre>$env_checksum(&lt;process-path-ex>)</pre>

  <p>Return the environment checksum for change tracking.</p>

  <h2 id="functions-target-triplet">5.14 Target Triplet Functions</h2>

  <p>The <code>$target_triplet.*()</code> function family contains function
  that operate on the <code>target_triplet</code> type that represents the
  ubiquitous <code><i>cpu</i>-<i>vendor</i>-<i>os</i></code> target platform
  triplet.</p>

  <h3 id="functions-target_triplet-string">5.14.1
  <code>$target_triplet.string()</code></h3>

  <pre>$string(&lt;target-triplet>)</pre>

  <p>Return the canonical (that is, without the <code>unknown</code> vendor
  component) target triplet string.</p>

  <h3 id="functions-target_triplet-representation">5.14.2
  <code>$target_triplet.representation()</code></h3>

  <pre>$representation(&lt;target-triplet>)</pre>

  <p>Return the complete target triplet string that always contains the vendor
  component.</p>

  <h1 id="directives">6 Directives</h1>

  <p><span class="note">This chapter is a work in progress and is
  incomplete.</span></p>

  <h2 id="directives-define">6.1 <code>define</code></h2>

  <pre>define &lt;derived>: &lt;base></pre>

  <p>Define a new target type <code>&lt;derived></code> by inheriting from
  existing target type <code>&lt;base></code>. See <a
  href="#targets-types">Target Types</a> for details.</p>

  <h2 id="directives-include">6.2 <code>include</code></h2>

  <pre>include &lt;file>
include &lt;directory></pre>

  <p>Load the specified file (the first form) or <code>buildfile</code> in the
  specified directory (the second form). In both cases the file is loaded in
  the scope corresponding to its directory. Subsequent inclusions of the same
  file are automatically ignored. See also <a
  href="#directives-source"><code>source</code></a>.</p>

  <h2 id="directives-source">6.3 <code>source</code></h2>

  <pre>source &lt;file></pre>

  <p>Load the specified file in the current scope as if its contents were
  copied and pasted in place of the <code>source</code> directive. Note that
  subsequent sourcing of the same file in the same scope are not automatically
  ignored.  See also <a
  href="#directives-include"><code>include</code></a>.</p>

  <h1 id="attributes">7 Attributes</h1>

  <p><span class="note">This chapter is a work in progress and is
  incomplete.</span></p>

  <p>The only currently recognized target attribute is <code>rule_hint</code>
  which specifies the rule hint. Rule hints can be used to resolve ambiguity
  when multiple rules match the same target as well as to override an
  unambiguous match. For example, the following rule hint makes sure our
  executable is linked with the C++ compiler even though it only has C
  sources:</p>

  <pre>[rule_hint=cxx] exe{hello}: c{hello}</pre>

  <h1 id="name-patterns">8 Name Patterns</h1>

  <p>For convenience, in certain contexts, names can be generated with
  shell-like wildcard patterns. A name is a <i>name pattern</i> if its value
  contains one or more unquoted wildcard characters or character sequences.
  For example:</p>

  <pre>./: */                     # All (immediate) subdirectories
exe{hello}: {hxx cxx}{**}  # All C++ header/source files.
pattern = '*.txt'          # Literal '*.txt'.</pre>

  <p>Pattern-based name generation is not performed in certain contexts.
  Specifically, it is not performed in target names where it is interpreted as
  a pattern for target type/pattern-specific variable assignments. For
  example.</p>

  <pre>s = *.txt             # Variable assignment (performed).
./: cxx{*}            # Prerequisite names (performed).
cxx{*}: dist = false  # Target pattern (not performed).</pre>

  <p>In contexts where it is performed, it can be inhibited with quoting, for
  example:</p>

  <pre>pat = 'foo*bar'
./: cxx{'foo*bar'}</pre>

  <p>The following wildcards are recognized:</p>

  <pre>*     - match any number of characters (including zero)
?     - match any single character
[...] - match a character with a bracket expression</pre>

  <div class="note">
  <p>Currently only literal character and range bracket expressions are
  supported. Specifically, no character or equivalence classes, etc., are
  supported nor the special characters backslash-escaping. See the "Pattern
  Matching Notation" section in the POSIX "Shell Command Language"
  specification for details.</p>
  </div>

  <p>Note that some wildcard characters may have special meaning in certain
  contexts. For instance, <code>[</code> at the beginning of a value will be
  interpreted as the start of the attribute list while <code>?</code> and
  <code>[</code> in the eval context are part of the ternary operator and
  value subscript, respectively. In such cases the character will need to be
  escaped in order to be treated as a wildcard, for example:</p>

  <pre>x = \[1-9]-foo.txt
y = (foo.\?xx)
z = ($foo\[123].txt)</pre>

  <p>If a pattern ends with a directory separator, then it only matches
  directories. Otherwise, it only matches files. Matches that start with a dot
  (<code>.</code>) are automatically ignored unless the pattern itself also
  starts with this character.</p>

  <p>In addition to the above wildcards, <code>**</code> and <code>***</code>
  are recognized as wildcard sequences. If a pattern contains <code>**</code>,
  then it is matched just like <code>*</code> but in all the subdirectories,
  recursively, but excluding directories that contain the
  <code>.buildignore</code> file. The <code>***</code> wildcard behaves like
  <code>**</code> but also matches the start directory itself. For
  example:</p>

  <pre>exe{hello}: cxx{**}  # All C++ source files recursively.</pre>

  <p>A group-enclosed (<code>{}</code>) pattern value may be followed by
  inclusion/exclusion patterns/matches. A subsequent value is treated as an
  inclusion or exclusion if it starts with a literal, unquoted plus
  (<code>+</code>) or minus (<code>-</code>) sign, respectively. In this case
  the remaining group values, if any, must all be inclusions or exclusions. If
  the second value doesn't start with a plus or minus, then all the group
  values are considered independent with leading pluses and minuses not having
  any special meaning. For regularity as well as to allow patterns without
  wildcards, the first pattern can also start with the plus sign. For
  example:</p>

  <pre>exe{hello}: cxx{f* -foo}            # Exclude foo if exists.
exe{hello}: cxx{f* +bar}            # Include bar if exists.
exe{hello}: cxx{f* -fo?}            # Exclude foo and fox if exist.
exe{hello}: cxx{f* +b* -foo -bar}   # Exclude foo and bar if exist.
exe{hello}: cxx{+f* +b* -foo -bar}  # Same as above.
exe{hello}: cxx{+foo}               # Pattern without wildcards.
exe{hello}: cxx{f* b* -z*}          # Names matching three patterns.</pre>

  <p>Inclusions and exclusions are applied in the order specified and only to
  the result produced up to that point. The order of names in the result is
  unspecified. However, it is guaranteed not to contain duplicates. The first
  pattern and the following inclusions/exclusions must be consistent with
  regards to the type of filesystem entry they match. That is, they should all
  match either files or directories. For example:</p>

  <pre>exe{hello}: cxx{f* -foo +*oo}  # Exclusion has no effect.
exe{hello}: cxx{f* +*oo}       # Ok, no duplicates.
./: {*/ -build}                # Error: exclusion not a directory.</pre>

  <p>As a more realistic example, let's say we want to exclude source files
  that reside in the <code>test/</code> directories (and their subdirectories)
  anywhere in the tree. This can be achieved with the following pattern:</p>

  <pre>exe{hello}: cxx{** -***/test/**}</pre>

  <p>Similarly, if we wanted to exclude all source files that have the
  <code>-test</code> suffix:</p>

  <pre>exe{hello}: cxx{** -**-test}</pre>

  <p>In contrast, the following pattern only excludes such files from the top
  directory:</p>

  <pre>exe{hello}: cxx{** -*-test}</pre>

  <p>If many inclusions or exclusions need to be specified, then an
  inclusion/exclusion group can be used. For example:</p>

  <pre>exe{hello}: cxx{f* -{foo bar}}
exe{hello}: cxx{+{f* b*} -{foo bar}}</pre>

  <p>This is particularly useful if you would like to list the names to
  include or exclude in a variable. For example, this is how we can exclude
  certain files from compilation but still include them as ordinary file
  prerequisites (so that they are still included into the source
  distribution):</p>

  <pre>exc = foo.cxx bar.cxx
exe{hello}: cxx{+{f* b*} -{$exc}} file{$exc}</pre>

  <p>If we want to specify our pattern in a variable, then we have to use the
  explicit inclusion syntax, for example:</p>

  <pre>pat = 'f*'
exe{hello}: cxx{+$pat} # Pattern match.
exe{hello}: cxx{$pat}  # Literal 'f*'.

pat = '+f*'
exe{hello}: cxx{$pat}  # Literal '+f*'.

inc = 'f*'  'b*'
exc = 'f*o' 'b*r'
exe{hello}: cxx{+{$inc} -{$exc}}</pre>

  <p>One common situation that calls for exclusions is auto-generated source
  code. Let's say we have auto-generated command line parser in
  <code>options.hxx</code> and <code>options.cxx</code>. Because of the in/out
  of source builds, our name pattern may or may not find these files. Note,
  however, that we cannot just include them as non-pattern prerequisites. We
  also have to exclude them from the pattern match since otherwise we may end
  up with duplicate prerequisites. As a result, this is how we have to handle
  this case provided we want to continue using patterns to find other,
  non-generated source files:</p>

  <pre>exe{hello}: {hxx cxx}{* -options} {hxx cxx}{options}</pre>

  <p>If all our auto-generated source files have a common prefix or suffix,
  then we can exclude them wholesale with a pattern. For example, if all our
  generated files end with the `-options` suffix:</p>

  <pre>exe{hello}: {hxx cxx}{** -**-options} {hxx cxx}{foo-options bar-options}</pre>

  <p>If the name pattern includes an absolute directory, then the pattern
  match is performed in that directory and the generated names include
  absolute directories as well. Otherwise, the pattern match is performed in
  the <i>pattern base</i> directory. In buildfiles this is
  <code>src_base</code> while on the command line &#8211; the current working
  directory. In this case the generated names are relative to the base
  directory. For example, assuming we have the <code>foo.cxx</code> and
  <code>b/bar.cxx</code> source files:</p>

  <pre>exe{hello}: $src_base/cxx{**}  # $src_base/cxx{foo} $src_base/b/cxx{bar}
exe{hello}:           cxx{**}  #           cxx{foo}           b/cxx{bar}</pre>

  <p>Pattern matching as well as inclusion/exclusion logic is target
  type-specific. If the name pattern does not contain a type, then the
  <code>dir{}</code> type is assumed if the pattern ends with a directory
  separator and <code>file{}</code> otherwise.</p>

  <p>For the <code>dir{}</code> target type the trailing directory separator
  is added to the pattern and all the inclusion/exclusion patterns/matches
  that do not already end with one. Then the filesystem search is performed
  for matching directories. For example:</p>

  <pre>./: dir{* -build}  # Search for */, exclude build/.</pre>

  <p>For the <code>file{}</code> and <code>file{}</code>-based target types
  the default extension (if any) is added to the pattern and all the
  inclusion/exclusion patterns/matches that do not already contain an
  extension. Then the filesystem search is performed for matching files.</p>

  <p>For example, the <code>cxx{}</code> target type obtains the default
  extension from the <code>extension</code> variable (see <a
  href="#targets-types">Target Types</a> for background). Assuming we have the
  following line in our <code>root.build</code>:</p>

  <pre>cxx{*}: extension = cxx</pre>

  <p>And the following in our <code>buildfile</code>:</p>

  <pre>exe{hello}: {cxx}{* -foo -bar.cxx}</pre>

  <p>The pattern match will first search for all the files matching the
  <code>*.cxx</code> pattern in <code>src_base</code> and then exclude
  <code>foo.cxx</code> and <code>bar.cxx</code> from the result. Note also
  that target type-specific decorations are removed from the result. So in the
  above example if the pattern match produces <code>baz.cxx</code>, then the
  prerequisite name is <code>cxx{baz}</code>, not
  <code>cxx{baz.cxx}</code>.</p>

  <p>If the name generation cannot be performed because the base directory is
  unknown, target type is unknown, or the target type is not directory or
  file-based, then the name pattern is returned as is (that is, as an ordinary
  name). Project-qualified names are never considered to be patterns.</p>

  <h1 id="module-config">9 <code>config</code> Module</h1>

  <p><span class="note">This chapter is a work in progress and is
  incomplete.</span></p>

  <h2 id="module-config-hermetic">9.1 Hermetic Build Configurations</h2>

  <p>Hermetic build configurations save environment variables that affect the
  project along with other project configuration in the
  <code>build/config.build</code> file. These saved environment variables are
  then used instead of the current environment when performing operations on
  the project, thus making sure the project "sees" exactly the same
  environment as during configuration.</p>

  <div class="note">
  <p>While currently hermetic configurations only deal with the environment,
  in the future this functionality may be extended to also support disallowing
  changes to external resources (compilers, system headers and libraries,
  etc).</p>
  </div>

  <p>To create a hermetic configuration we use the
  <code>config.config.hermetic</code> configuration variable. For example:</p>

  <pre>$ b configure config.config.hermetic=true</pre>

  <div class="note">
  <p>Hermetic configurations are not the default because they are not without
  drawbacks. Firstly, a hermetic configuration may break if the saved
  environment becomes incompatible with the rest of the system. For example,
  you may re-install an external program (say, a compiler) into a different
  location and update your <code>PATH</code> to match the new setup. However,
  a hermetic configuration will "see" the first change but not the second.</p>

  <p>Another issue is the commands printed during a hermetic build: they are
  executed in the saved environment which may not match the environment in
  which the build system was invoked. As a result, we cannot easily re-execute
  such commands, which is often handy during build troubleshooting.</p>

  <p>It is also important to keep in mind that a non-hermetic build
  configuration does not break or produce incorrect results if the environment
  changes. Instead, changes to the environment are detected and affected
  targets are automatically rebuilt.</p>

  <p>The two use-cases where hermetic configurations are especially useful are
  when we need to save an environment which is not generally available (for
  example, an environment of a Visual Studio development command prompt) or
  when our build results need to exactly match the specific configuration (for
  example, because parts of the overall result have already been built and
  installed, as is the case with build system modules).</p>
  </div>

  <p>If we now examine <code>config.build</code>, we will see something along
  these lines:</p>

  <pre>$ cat build/config.build

config.config.hermetic = true
config.config.environment = CPATH CPLUS_INCLUDE_PATH PATH=...</pre>

  <div class="note">
  <p>Hermetic configuration support is built on top of the low-level
  <code>config.config.environment</code> configuration variable which allows
  us to specify custom environment variables and their values. Specifically,
  it contains a list of environment variable "sets"
  (<code><i>name</i>=<i>value</i></code>) and "unsets"
  (<code><i>name</i></code>). For example:</p>

  <pre>$ b configure \
  config.config.environment="PATH=/bin:/usr/bin LD_LIBRARY_PATH"</pre>

  <p>Specifying <code>config.config.hermetic=true</code> simply instructs the
  <code>config</code> module to collect and save in
  <code>config.config.environment</code> environment variables that affect the
  project. These include:</p>

  <ul>
  <li>built-in variables (such as <code>PATH</code> and
  <code>LD_LIBRARY_PATH</code> or equivalent),</li>

  <li>variables that affect external programs as reported by build system
  modules (such as <code>CPLUS_INCLUDE_PATH</code> reported by the
  <code>cxx</code> module) or by imported programs via metadata,</li>

  <li>variables reported by the project itself with the
  <code>config.environment</code> directive (discussed below).</li>
  </ul>
  </div>

  <p>Reconfiguring a hermetic configuration preserves the saved environment
  unless <i>re-hermetization</i> is explicitly requested with the
  <code>config.config.hermetic.reload</code> configuration variable. For
  example:</p>

  <pre>$ b configure config.config.hermetic.reload=true</pre>

  <div class="note">
  <p>Note that <code>config.config.hermetic.reload</code> is transient and is
  not stored in <code>config.build</code>. In other words, there is no way to
  create a hermetic configuration that is re-hermetized by default during
  reconfiguration.</p>
  </div>

  <p>To <i>de-hermetize</i> a hermetic build configuration, reconfigure it
  with <code>config.config.hermetic=false</code>.</p>

  <div class="note">
  <p>The <code>config.config.hermetic</code> variable has essentially a
  tri-state value: <code>true</code> means keep hermetized (save the
  environment in <code>config.config.environment</code>), <code>false</code>
  means keep de-hermetized (clear <code>config.config.environment</code>) and
  <code>null</code> or undefined means don't touch
  <code>config.config.environment</code>.</p>
  </div>

  <p>We can adjust the set of environment variables saved in a hermetic
  configuration using the <code>config.config.hermetic.environment</code>
  configuration variable. It contains a list of inclusions
  (<code><i>name</i></code>) and exclusions (<code><i>name</i>@false</code>)
  which are applied to the final set of environment variables that affect the
  project. For example:</p>

  <pre>LC_ALL=C b configure \
  config.config.hermetic=true \
  config.config.hermetic.environment="LC_ALL PATH@false"</pre>

  <p>Typically, the set of environment variables that affect the project is
  discovered automatically. Specifically, modules that we use (such as
  <code>cxx</code>) are expected to report the environment variables that
  affect the programs they invoke (such as the C++ compiler). Similarly,
  programs that we import in our <code>buildfiles</code> (for example to use
  in ad hoc recipes) are expected to report environment variables that affect
  them as part of their metadata.</p>

  <p>However, there are situations where we need to report an environment
  variable manually. These include calling the <code>$getenv()</code> function
  from a <code>buildfile</code> or invoking a program (either in an ad hoc
  recipe, the <code>run</code> directive, or the <code>$run*()</code> function
  family) that either does not provide the metadata or does not report the
  environment as part of it. In such cases we should report the environment
  variable manually using the <code>config.environment</code> directive. For
  example:</p>

  <pre>config.environment USE_FOO

foo = $getenv(USE_FOO)

if ($foo != [null])
  cxx.poptions += "-DUSE_FOO=$foo"</pre>

  <p>Additionally, if invoking a program in an ad hoc recipe that either does
  not provide the metadata or does not report the environment as part of it,
  then we additionally should track the changes to the relevant environment
  variables manually using the <code>depdb env</code> builtin. For
  example:</p>

  <pre>import! foo = foo%exe{foo} # Uses FOO and BAR environment variables.

config.environment FOO BAR

file{output}: file{input} $foo
{{
  diag foo $>
  depdb env FOO BAR
  $foo $path($&lt;[0]) >$path($>)
}}</pre>

  <div class="note">
  <p>Normally, we would want to report variables that affect the build result
  rather than build byproducts (for example, diagnostics). This is, for
  example, the reason why locale-related environment variables are not saved
  by default. Also, sometime environment variables only affect certain modes
  of a program. If such modes are not used, then there is no need to report
  the corresponding variables.</p>
  </div>

  <h1 id="module-test">10 <code>test</code> Module</h1>

  <p><span class="note">This chapter is a work in progress and is
  incomplete.</span></p>

  <p>The targets to be tested as well as the tests/groups from testscripts to
  be run can be narrowed down using the <code>config.test</code> variable.
  While this value is normally specified as a command line override (for
  example, to quickly re-run a previously failed test), it can also be
  persisted in <code>config.build</code> in order to create a configuration
  that will only run a subset of tests by default. For example:</p>

  <pre>b test config.test=foo/exe{driver} # Only test foo/exe{driver} target.
b test config.test=bar/baz         # Only run bar/baz testscript test.</pre>

  <p>The <code>config.test</code> variable contains a list of
  <code>@</code>-separated pairs with the left hand side being the target and
  the right hand side being the testscript id path. Either can be omitted
  (along with <code>@</code>). If the value contains a target type or ends
  with a directory separator, then it is treated as a target name. Otherwise
  &#8211; an id path. The targets are resolved relative to the root scope
  where the <code>config.test</code> value is set. For example:</p>

  <pre>b test config.test=foo/exe{driver}@bar</pre>

  <p>To specify multiple id paths for the same target we can use the pair
  generation syntax:</p>

  <pre>b test config.test=foo/exe{driver}@{bar baz}</pre>

  <p>If no targets are specified (only id paths), then all the targets are
  tested (with the testscript tests to be run limited to the specified id
  paths). If no id paths are specified (only targets), then all the testscript
  tests are run (with the targets to be tested limited to the specified
  targets). An id path without a target applies to all the targets being
  considered.</p>

  <p>A directory target without an explicit target type (for example,
  <code>foo/</code>) is treated specially. It enables all the tests at and
  under its directory. This special treatment can be inhibited by specifying
  the target type explicitly (for example, <code>dir{foo/}</code>).</p>

  <p>The test execution time can be limited using the
  <code>config.test.timeout</code> variable. Its value has the
  <code>&lt;operation-timeout>/&lt;test-timeout></code> form where the
  timeouts are specified in seconds and either of them (but not both) can be
  omitted. The left hand side sets the timeout for the whole <code>test</code>
  operation and the right hand side &#8211; for individual tests. The zero
  value clears the previously set timeout. For example:</p>

  <pre>b test config.test.timeout=20   # Test operation.
b test config.test.timeout=20/5 # Test operation and individual tests.
b test config.test.timeout=/5   # Individual tests.</pre>

  <p>The test timeout can be specified on multiple nested root scopes. For
  example, we can specify a greater timeout for the entire build configuration
  and lesser ones for individual projects. The tests must complete before the
  nearest of the enclosing scope timeouts. Failed that, the timed out tests
  are terminated forcibly causing the entire <code>test</code> operation to
  fail. See also the <a
  href="build2-testscript-manual.xhtml#builtins-timeout"><code>timeout</code></a>
  builtin for specifying timeouts from within the tests and test groups.</p>

  <p>The programs being tested can be executed via a <i>runner program</i> by
  specifying the <code>config.test.runner</code> variable. Its value has the
  <code>&lt;path> [&lt;options>]</code> form. For example:</p>

  <pre>b test config.test.runner="valgrind -q"</pre>

  <p>When the runner program is specified, commands of simple and Testscript
  tests are automatically adjusted so that the runner program is executed
  instead, with the test command passed to it as arguments. For ad hoc test
  recipes, the runner program has to be handled explicitly. Specifically, if
  <code>config.test.runner</code> is specified, the
  <code>test.runner.path</code> and <code>test.runner.options</code> variables
  contain the runner program path and options, respectively, and are set to
  <code>null</code> otherwise. These variables can be used by ad hoc recipes
  to detect the presence of the runner program and, if so, arrange appropriate
  execution of desired commands. For example:</p>

  <pre>exe{hello}:
% test
{{
  diag test $>

  cmd = ($test.runner.path == [null] \
    ? $> \
    : $test.runner.path $test.runner.options $path($>))

  $cmd 'World' >>>?'Hello, World!'
}}</pre>

  <h1 id="module-install">11 <code>install</code> Module</h1>

  <p><span class="note">This chapter is a work in progress and is
  incomplete.</span></p>

  <p>The <code>install</code> module provides support for installing and
  uninstalling projects.</p>

  <p>As briefly discussed in the <a
  href="#intro-operations-install">Installing</a> section of the Introduction,
  the <code>install</code> module defines the following standard installation
  locations:</p>

  <pre>name          default                                 config.install.*
                                                      (c.i.*) override
----          -------                                 ----------------
root                                                  c.i.root

data_root     root/                                   c.i.data_root
exec_root     root/                                   c.i.exec_root

bin           exec_root/bin/                          c.i.bin
sbin          exec_root/sbin/                         c.i.sbin
lib           exec_root/lib/&lt;private>/                c.i.lib
libexec       exec_root/libexec/&lt;private>/&lt;project>/  c.i.libexec
pkgconfig     lib/pkgconfig/                          c.i.pkgconfig

etc           data_root/etc/                          c.i.etc
include       data_root/include/&lt;private>/            c.i.include
include_arch  include/                                c.i.include_arch
share         data_root/share/                        c.i.share
data          share/&lt;private>/&lt;project>/              c.i.data
buildfile     share/build2/export/&lt;project>/          c.i.buildfile

doc           share/doc/&lt;private>/&lt;project>/          c.i.doc
legal         doc/                                    c.i.legal
man           share/man/                              c.i.man
man&lt;N>        man/man&lt;N>/                             c.i.man&lt;N></pre>

  <p>The <code>include_arch</code> location is meant for architecture-specific
  files, such as configuration headers. By default it's the same as
  <code>include</code> but can be configured by the user to a different value
  (for example, <code>/usr/include/x86_64-linux-gnu/</code>) for platforms
  that support multiple architectures from the same installation location.
  This is how one would normally use it from a <code>buildfile</code>:</p>

  <pre># The configuration header may contain target architecture-specific
# information so install it into include_arch/ instead of include/.
#
h{*}:      install = include/libhello/
h{config}: install = include_arch/libhello/</pre>

  <p>The <code>buildfile</code> location is meant for exported buildfiles that
  can be imported by other projects. If a project contains any
  <code>**.build</code> buildfiles in its <code>build/export/</code> directory
  (or <code>**.build2</code> and <code>build2/export/</code> in the
  alternative naming scheme), then they are automatically installed into this
  location (recreating subdirectories).</p>

  <p>The <code>&lt;project></code>, <code>&lt;version></code>, and
  <code>&lt;private></code> substitutions in these
  <code>config.install.*</code> values are replaced with the project name,
  version, and private subdirectory, respectively. If either is empty, then
  the corresponding directory component is ignored.</p>

  <p>The optional private installation subdirectory
  (<code>&lt;private></code>) mechanism can be used to hide the implementation
  details of a project. This is primarily useful when installing an executable
  that depends on a bunch of libraries into a shared location, such as
  <code>/usr/local/</code>. By hiding the libraries in the private
  subdirectory we can make sure that they will not interfere with anything
  that is already installed into such a shared location by the user and that
  any further such installations won't interfere with our executable.</p>

  <p>The private installation subdirectory is specified with the
  <code>config.install.private</code> variable. Its value must be a relative
  directory and may include multiple components. For example:</p>

  <pre>$ b install                         \
    config.install.root=/usr/local/ \
    config.install.private=hello/</pre>

  <div class="note">
  <p>If you are relying on your system's dynamic linker defaults to
  automatically find shared libraries that are installed with your executable,
  then adding the private installation subdirectory will most definitely cause
  this to stop working. The recommended way to resolve this problem is to use
  <i>rpath</i>, for example:</p>

  <pre>$ b install                       \
  config.install.root=/usr/local/ \
  config.install.private=hello/   \
  config.bin.rpath=/usr/local/lib/hello/</pre>
  </div>

  <h2 id="install-reloc">11.1 Relocatable Installation</h2>

  <p>A relocatable installation can be moved to a directory other than its
  original installation location. Note that the installation should be moved
  as a whole preserving the directory structure under its root
  (<code>config.install.root</code>). To request a relocatable installation,
  set the <code>config.install.relocatable</code> variable to
  <code>true</code>. For example:</p>

  <pre>$ b install                          \
    config.install.root=/tmp/install \
    config.install.relocatable=true</pre>

  <p>A relocatable installation is achieved by using paths relative to one
  filesystem entry within the installation to locate another. Some examples
  include:</p>

  <ul>
  <li>Paths specified in <code>config.bin.rpath</code> are made relative using
  the <code>$ORIGIN</code> (Linux, BSD) or <code>@loader_path</code> (Mac OS)
  mechanisms.</li>

  <li>Paths in the generated <code>pkg-config</code> files are made relative
  to the <code>${pcfiledir}</code> built-in variable.</li>

  <li>Paths in the generated installation manifest
  (<code>config.install.manifest</code>) are made relative to the location of
  the manifest file.</li>
  </ul>

  <p>While these common aspects are handled automatically, if a projects
  relies on knowing its installation location, then it will most likely need
  to add manual support for relocatable installations.</p>

  <p>As an example, consider an executable that supports loading plugins and
  requires the plugin installation directory to be embedded into the
  executable during the build. The common way to support relocatable
  installations for such cases is to embed a path relative to the executable
  and complete it at runtime, normally by resolving the executable's path and
  using its directory as a base.</p>

  <p>If you would like to always use the relative path, regardless of whether
  the installation is relocatable of not, then you can obtain the library
  installation directory relative to the executable installation directory
  like this:</p>

  <pre>plugin_dir = $install.resolve($install.lib, $install.bin)</pre>

  <p>Alternatively, if you would like to continue using absolute paths for
  non-relocatable installations, then you can use something like this:</p>

  <pre>plugin_dir = $install.resolve( \
  $install.lib,                \
  ($install.relocatable ? $install.bin : [dir_path] ))</pre>

  <p>Finally, if you are unable to support relocatable installations, the
  correct way to handle this is to assert this fact in <code>root.build</code>
  of your project, for example:</p>

  <pre>assert (!$install.relocatable) 'relocatable installation not supported'</pre>

  <h2 id="install-filter">11.2 Installation Filtering</h2>

  <p>While project authors determine what gets installed at the
  <code>buildfile</code> level, the users of the project can further filter
  the installation using the <code>config.install.filter</code> variable.</p>

  <p>The value of this variable is a list of key-value pairs that specify the
  filesystem entries to include or exclude from the installation. For example,
  the following filters will omit installing headers and static libraries
  (notice the quoting of the wildcard).</p>

  <pre>$ b install config.install.filter='include/@false "*.a"@false'</pre>

  <p>The key in each pair is a file or directory path or a path wildcard
  pattern. If a key is relative and contains a directory component or is a
  directory, then it is treated relative to the corresponding
  <code>config.install.*</code> location. Otherwise (simple path, normally a
  pattern), it is matched against the leaf of any path. Note that if an
  absolute path is specified, it should be without the
  <code>config.install.chroot</code> prefix.</p>

  <p>The value in each pair is either <code>true</code> (include) or
  <code>false</code> (exclude). The filters are evaluated in the order
  specified and the first match that is found determines the outcome. If no
  match is found, the default is to include. For a directory, while
  <code>false</code> means exclude all the sub-paths inside this directory,
  <code>true</code> does not mean that all the sub-paths will be included
  wholesale. Rather, the matched component of the sub-path is treated as
  included with the rest of the components matched against the following
  sub-filters. For example:</p>

  <pre>$ b install config.install.filter='
   include/x86_64-linux-gnu/@true
   include/x86_64-linux-gnu/details/@false
   include/@false'</pre>

  <p>The <code>true</code> or <code>false</code> value may be followed by
  comma and the <code>symlink</code> modifier to only apply to symlink
  filesystem entries. For example:</p>

  <pre>$ b config.install.filter='"*.so"@false,symlink'</pre>

  <p>A filter can be negated by specifying <code>!</code> as the first pair.
  For example:</p>

  <pre>$ b install config.install.filter='! include/@false "*.a"@false'</pre>

  <p>Note that the filtering mechanism only affects what gets physically
  copied to the installation directory without affecting what gets built for
  install or the view of what gets installed at the <code>buildfile</code>
  level. For example, given the <code>include/@false *.a@false</code> filters,
  static libraries will still be built (unless arranged not to with
  <code>config.bin.lib</code>) and the <code>pkg-config</code> files will
  still end up with <code>-I</code> options pointing to the header
  installation directory. Note also that this mechanism applies to both
  <code>install</code> and <code>uninstall</code> operations.</p>

  <div class="note">
  <p>If you are familiar with the Debian or Fedora packaging, this mechanism
  is somewhat similar to (and can be used for a similar purpose as) the
  Debian's <code>.install</code> files and Fedora's <code>%files</code> spec
  file sections, which are used to split the installation into multiple binary
  packages.</p>
  </div>

  <p>As another example, the following filters will omit all the
  development-related files (headers, <code>pkg-config</code> files, static
  libraries, and shared library symlinks; assuming the platform uses the
  <code>.a</code>/<code>.so</code> extensions for the libraries):</p>

  <pre>$ b install config.install.filter='
   include/@false
   pkgconfig/@false
   "lib/*.a"@false
   "lib/*.so"@false,symlink'</pre>

  <h1 id="module-version">12 <code>version</code> Module</h1>

  <p>A project can use any version format as long as it meets the package
  version requirements. The toolchain also provides additional functionality
  for managing projects that conform to the <code>build2</code> <i>standard
  version</i> format. If you are starting a new project that uses
  <code>build2</code>, you are strongly encouraged to use this versioning
  scheme. It is based on much thought and, often painful, experience. If you
  decide not to follow this advice, you are essentially on your own where
  version management is concerned.</p>

  <p>The standard <code>build2</code> project version conforms to <a
  href="http://semver.org">Semantic Versioning</a> and has the following
  form:</p>

  <pre>&lt;major>.&lt;minor>.&lt;patch>[-&lt;prerel>]</pre>

  <p>For example:</p>

  <pre>1.2.3
1.2.3-a.1
1.2.3-b.2</pre>

  <p>The <code>build2</code> package version that uses the standard project
  version will then have the following form (<i>epoch</i> is the versioning
  scheme version and <i>revision</i> is the package revision):</p>

  <pre>[+&lt;epoch>-]&lt;major>.&lt;minor>.&lt;patch>[-&lt;prerel>][+&lt;revision>]</pre>

  <p>For example:</p>

  <pre>1.2.3
1.2.3+1
+2-1.2.3-a.1+2</pre>

  <p>The <i>major</i>, <i>minor</i>, and <i>patch</i> should be numeric values
  between <code>0</code> and <code>99999</code> and all three cannot be zero
  at the same time. For initial development it is recommended to use
  <code>0</code> for <i>major</i>, start with version <code>0.1.0</code>, and
  change to <code>1.0.0</code> once things stabilize.</p>

  <p>In the context of C and C++ (or other compiled languages), you should
  increment <i>patch</i> when making binary-compatible changes, <i>minor</i>
  when making source-compatible changes, and <i>major</i> when making breaking
  changes. While the binary compatibility must be set in stone, the source
  compatibility rules can sometimes be bent. For example, you may decide to
  make a breaking change in a rarely used interface as part of a minor release
  (though this is probably still a bad idea if your library is widely depended
  upon). Note also that in the context of C++ deciding whether a change is
  binary-compatible is a non-trivial task. There are resources that list the
  rules but no automated tooling yet. If unsure, increment <i>minor</i>.</p>

  <p>If present, the <i>prerel</i> component signifies a pre-release. Two
  types of pre-releases are supported by the standard versioning scheme:
  <i>final</i> and <i>snapshot</i> (non-pre-release versions are naturally
  always final). For final pre-releases the <i>prerel</i> component has the
  following form:</p>

  <pre>(a|b).&lt;num></pre>

  <p>For example:</p>

  <pre>1.2.3-a.1
1.2.3-b.2</pre>

  <p>The letter '<code>a</code>' signifies an alpha release and
  '<code>b</code>' &#8211; beta. The alpha/beta numbers (<i>num</i>) should be
  between 1 and 499.</p>

  <p>Note that there is no support for release candidates. Instead, it is
  recommended that you use later-stage beta releases for this purpose (and, if
  you wish, call them "release candidates" in announcements, etc).</p>

  <p>What version should be used during development? The common approach is to
  increment to the next version and use that until the release. This has one
  major drawback: if we publish intermediate snapshots (for example, for
  testing) they will all be indistinguishable both between each other and,
  even worse, from the final release. One way to remedy this is to increment
  the pre-release number before each publication. However, unless automated,
  this will be burdensome and error-prone. Also, there is a real possibility
  of running out of version numbers if, for example, we do continuous
  integration by publishing and testing each commit.</p>

  <p>To address this, the standard versioning scheme supports <i>snapshot
  pre-releases</i> with the <i>prerel</i> component having the following
  extended form:</p>

  <pre>(a|b).&lt;num>.&lt;snapsn>[.&lt;snapid>]</pre>

  <p>For example:</p>

  <pre>1.2.3-a.1.20180319215815.26efe301f4a7</pre>

  <p>In essence, a snapshot pre-release is after the previous final release
  but before the next (<code>a.1</code> and, perhaps, <code>a.2</code> in the
  above example) and is uniquely identified by the snapshot sequence number
  (<i>snapsn</i>) and optional snapshot id (<i>snapid</i>).</p>

  <p>The <i>num</i> component has the same semantics as in the final
  pre-releases except that it can be <code>0</code>. The <i>snapsn</i>
  component should be either the special value '<code>z</code>' or a numeric,
  non-zero value that increases for each subsequent snapshot. It must not be
  longer than 16 decimal digits. The <i>snapid</i> component, if present,
  should be an alpha-numeric value that uniquely identifies the snapshot. It
  is not required for version comparison (<i>snapsn</i> should be sufficient)
  and is included for reference. It must not be longer than 16 characters.</p>

  <p>Where do the snapshot number and id come from? Normally from the version
  control system. For example, for <code>git</code>, <i>snapsn</i> is the
  commit date in the <i>YYYYMMDDhhmmss</i> form and UTC timezone and
  <i>snapid</i> is a 12-character abbreviated commit id. As discussed below,
  the <code>build2</code> <code>version</code> module extracts and manages all
  this information automatically (but the use of <code>git</code> commit dates
  is not without limitations; see below for details).</p>

  <p>The special '<code>z</code>' <i>snapsn</i> value identifies the
  <i>latest</i> or <i>uncommitted</i> snapshot. It is chosen to be greater
  than any other possible <i>snapsn</i> value and its use is discussed further
  below.</p>

  <p>As an illustration of this approach, let's examine how versions change
  during the lifetime of a project:</p>

  <pre>0.1.0-a.0.z     # development after a.0
0.1.0-a.1       # pre-release
0.1.0-a.1.z     # development after a.1
0.1.0-a.2       # pre-release
0.1.0-a.2.z     # development after a.2
0.1.0-b.1       # pre-release
0.1.0-b.1.z     # development after b.1
0.1.0           # release
0.1.1-b.0.z     # development after b.0 (bugfix)
0.2.0-a.0.z     # development after a.0
0.1.1           # release (bugfix)
1.0.0           # release (jumped straight to 1.0.0)
...</pre>

  <p>As shown in the above example, there is nothing wrong with "jumping" to a
  further version (for example, from alpha to beta, or from beta to release,
  or even from alpha to release). We cannot, however, jump backwards (for
  example, from beta back to alpha). As a result, a sensible strategy is to
  start with <code>a.0</code> since it can always be upgraded (but not
  downgraded) at a later stage.</p>

  <p>When it comes to the version control systems, the recommended workflow is
  as follows: The change to the final version should be the last commit in the
  (pre-)release. It is also a good idea to tag this commit with the project
  version. A commit immediately after that should change the version to a
  snapshot, "opening" the repository for development.</p>

  <p>The project version without the snapshot part can be represented as a
  64-bit decimal value comparable as integers (for example, in preprocessor
  directives). The integer representation has the following form:</p>

  <pre>AAAAABBBBBCCCCCDDDE

AAAAA - major
BBBBB - minor
CCCCC - patch
DDD   - alpha / beta (DDD + 500)
E     - final (0) / snapshot (1)</pre>

  <p>If the <i>DDDE</i> value is not zero, then it signifies a pre-release. In
  this case one is subtracted from the <i>AAAAABBBBBCCCCC</i> value. An alpha
  number is stored in <i>DDD</i> as is while beta &#8211; incremented by
  <code>500</code>. If <i>E</i> is <code>1</code>, then this is a snapshot
  after <i>DDD</i>.</p>

  <p>For example:</p>

  <pre>             AAAAABBBBBCCCCCDDDE
0.1.0        0000000001000000000
0.1.2        0000000001000020000
1.2.3        0000100002000030000
2.2.0-a.1    0000200001999990010
3.0.0-b.2    0000299999999995020
2.2.0-a.1.z  0000200001999990011</pre>

  <p>A project that uses standard versioning can rely on the
  <code>build2</code> <code>version</code> module to simplify and automate
  version managements. The <code>version</code> module has two primary
  functions: eliminate the need to change the version anywhere except in the
  project's manifest file and automatically extract and propagate the snapshot
  information (sequence number and id).</p>

  <p>The <code>version</code> module must be loaded in the project's
  <code>bootstrap.build</code>. While being loaded, it reads the project's
  manifest and extracts its version (which must be in the standard form). The
  version is then parsed and presented as the following build system variables
  (which can be used in the buildfiles):</p>

  <pre>[string] version                     # +2-1.2.3-b.4.1234567.deadbeef+3

[string] version.project             # 1.2.3-b.4.1234567.deadbeef
[uint64] version.project_number      # 0000100002000025041
[string] version.project_id          # 1.2.3-b.4.deadbeef

[bool]   version.stub                # false (true for 0[+&lt;revision>])

[uint64] version.epoch               # 2

[uint64] version.major               # 1
[uint64] version.minor               # 2
[uint64] version.patch               # 3

[bool]   version.alpha               # false
[bool]   version.beta                # true
[bool]   version.pre_release         # true
[string] version.pre_release_string  # b.4
[uint64] version.pre_release_number  # 4

[bool]   version.snapshot            # true
[uint64] version.snapshot_sn         # 1234567
[string] version.snapshot_id         # deadbeef
[string] version.snapshot_string     # 1234567.deadbeef
[bool]   version.snapshot_committed  # true

[uint64] version.revision            # 3</pre>

  <p>As a convenience, the <code>version</code> module also extracts the
  <code>summary</code> and <code>url</code> manifest values and sets them as
  the following build system variables (this additional information is used,
  for example, when generating the <code>pkg-config</code> files):</p>

  <pre>[string] project.summary
[string] project.url</pre>

  <p>If the version is the latest snapshot (that is, it's in the
  <code>.z</code> form), then the <code>version</code> module extracts the
  snapshot information from the version control system used by the project.
  Currently only <code>git</code> is supported with the following
  semantics.</p>

  <p>If the project's source directory (<code>src_root</code>) is clean (that
  is, it does not have any changed or untracked files), then the
  <code>HEAD</code> commit date and id are used as the snapshot number and id,
  respectively.</p>

  <p>Otherwise (that is, the project is between commits), the
  <code>HEAD</code> commit date is incremented by one second and is used as
  the snapshot number with no id. While we can work with such uncommitted
  snapshots locally, we should not distribute or publish them since they are
  indistinguishable from each other.</p>

  <p>Finally, if the project does not have <code>HEAD</code> (that is, the
  project has no commits yet), the special <code>19700101000000</code> (UNIX
  epoch) commit date is used.</p>

  <p>The use of <code>git</code> commit dates for snapshot ordering has its
  limitations: they have one second resolution which means it is possible to
  create two commits with the same date (but not the same commit id and thus
  snapshot id). We also need all the committers to have a reasonably accurate
  clock. Note, however, that in case of a commit date clash/ordering issue, we
  still end up with distinct versions (because of the commit id) &#8211; they
  are just not ordered correctly. As a result, we feel that the risks are
  justified when the only alternative is manual version management (which is
  always an option, nevertheless).</p>

  <p>When we prepare a source distribution of a snapshot, the
  <code>version</code> module automatically adjusts the package name to
  include the snapshot information as well as patches the manifest file in the
  distribution with the snapshot number and id (that is, replacing
  <code>.z</code> in the version value with the actual snapshot information).
  The result is a package that is specific to this commit.</p>

  <p>Besides extracting the version information and making it available as
  individual components, the <code>version</code> module also provides rules
  for installing the manifest file as well as automatically generating version
  headers (or other similar version-based files).</p>

  <p>By default the project's <code>manifest</code> file is installed as
  documentation, just like other <code>doc{}</code> targets (thus replacing
  the <code>version</code> file customarily shipped in the project root
  directory). The manifest installation rule in the <code>version</code>
  module in addition patches the installed manifest file with the actual
  snapshot number and id, just like during the preparation of
  distributions.</p>

  <p>The version header rule is based on the <a
  href="#module-in"><code>in</code></a> module rule and can be used to
  preprocess a template file with version information. While it is usually
  used to generate C/C++ version headers (thus the name), it can really
  generate any kind of files.</p>

  <p>The rule matches a <code>file</code>-based target that has the
  corresponding <code>in</code> prerequisite and also depends on the project's
  <code>manifest</code> file. As an example, let's assume we want to
  auto-generate a header called <code>version.hxx</code> for our
  <code>libhello</code> library. To accomplish this we add the
  <code>version.hxx.in</code> template as well as something along these lines
  to our <code>buildfile</code>:</p>

  <pre>lib{hello}: {hxx cxx}{** -version} hxx{version}

hxx{version}: in{version} $src_root/file{manifest}</pre>

  <p>The header rule is a line-based preprocessor that substitutes fragments
  enclosed between (and including) a pair of dollar signs (<code>$</code>)
  with <code>$$</code> being the escape sequence (see the <a
  href="#module-in"><code>in</code></a> module for details). As an example,
  let's assume our <code>version.hxx.in</code> contains the following
  lines:</p>

  <pre>#ifndef LIBHELLO_VERSION

#define LIBHELLO_VERSION     $libhello.version.project_number$ULL
#define LIBHELLO_VERSION_STR "$libhello.version.project$"

#endif</pre>

  <p>If our <code>libhello</code> is at version <code>1.2.3</code>, then the
  generated <code>version.hxx</code> will look like this:</p>

  <pre>#ifndef LIBHELLO_VERSION

#define LIBHELLO_VERSION     100002000030000ULL
#define LIBHELLO_VERSION_STR "1.2.3"

#endif</pre>

  <p>The first component after the opening <code>$</code> should be either the
  name of the project itself (like <code>libhello</code> above) or a name of
  one of its dependencies as listed in the manifest. If it is the project
  itself, then the rest can refer to one of the <code>version.*</code>
  variables that we discussed earlier (in reality it can be any variable
  visible from the project's root scope).</p>

  <p>If the name refers to one of the dependencies (that is, projects listed
  with <code>depends:</code> in the manifest), then the following special
  substitutions are recognized:</p>

  <pre>$&lt;name>.version$                           - textual version constraint
$&lt;name>.condition(&lt;VERSION>[,&lt;SNAPSHOT>])$ - numeric satisfaction condition
$&lt;name>.check(&lt;VERSION>[,&lt;SNAPSHOT>])$     - numeric satisfaction check</pre>

  <p>Here <i>VERSION</i> is the version number macro and the optional
  <i>SNAPSHOT</i> is the snapshot number macro. The snapshot is only required
  if you plan to include snapshot information in your dependency
  constraints.</p>

  <p>As an example, let's assume our <code>libhello</code> depends on
  <code>libprint</code> which is reflected with the following line in our
  manifest:</p>

  <pre>depends: libprint >= 2.3.4</pre>

  <p>We also assume that <code>libprint</code> provides its version
  information in the <code>libprint/version.hxx</code> header and uses
  analogous-named macros. Here is how we can add a version check to our
  <code>version.hxx.in</code>:</p>

  <pre>#ifndef LIBHELLO_VERSION

#define LIBHELLO_VERSION     $libhello.version.project_number$ULL
#define LIBHELLO_VERSION_STR "$libhello.version.project$"

#include &lt;libprint/version.hxx>

$libprint.check(LIBPRINT_VERSION)$

#endif</pre>

  <p>After the substitution our <code>version.hxx</code> header will look like
  this:</p>

  <pre>#ifndef LIBHELLO_VERSION

#define LIBHELLO_VERSION     100002000030000ULL
#define LIBHELLO_VERSION_STR "1.2.3"

#include &lt;libprint/version.hxx>

#ifdef LIBPRINT_VERSION
#  if !(LIBPRINT_VERSION >= 200003000040000ULL)
#    error incompatible libprint version, libprint >= 2.3.4 is required
#  endif
#endif

#endif</pre>

  <p>The <code>version</code> and <code>condition</code> substitutions are the
  building blocks of the <code>check</code> substitution. For example, here is
  how we can implement a check with a customized error message:</p>

  <pre>#if !($libprint.condition(LIBPRINT_VERSION)$)
#  error bad libprint, need libprint $libprint.version$
#endif</pre>

  <p>The <code>version</code> module also treats one dependency in a special
  way: if you specify the required version of the build system in your
  manifest, then the module will automatically check it for you. For example,
  if we have the following line in our manifest:</p>

  <pre>depends: * build2 >= 0.5.0</pre>

  <p>And someone tries to build our project with <code>build2</code>
  <code>0.4.0</code>, then they will see an error like this:</p>

  <pre>build/bootstrap.build:3:1: error: incompatible build2 version
  info: running 0.4.0
  info: required 0.5.0</pre>

  <p>What version constraints should be used when depending on another
  project? We start with a simple case where we depend on a release. Let's say
  <code>libprint</code> <code>2.3.0</code> added a feature that we need in our
  <code>libhello</code>. If <code>libprint</code> follows the source/binary
  compatibility guidelines discussed above, then any <code>2.X.Y</code>
  version should work provided <code>X >= 3</code>. And this how we can
  specify it in the manifest:</p>

  <pre>depends: libprint ^2.3.0</pre>

  <p>Let's say we are now working on <code>libhello</code> <code>2.0.0</code>
  and would like to start using features from <code>libprint</code>
  <code>3.0.0</code>. However, currently, only pre-releases of
  <code>3.0.0</code> are available. If you would like to add a dependency on a
  pre-release (most likely from your own pre-release), then the recommendation
  is to only allow a specific version, essentially "expiring" the combination
  as soon as newer versions become available. For example:</p>

  <pre>version: 2.0.0-b.1
depends: libprint == 3.0.0-b.2</pre>

  <p>Finally, let's assume we are feeling adventurous and would like to test
  development snapshots of <code>libprint</code> (most likely from our own
  snapshots). In this case the recommendation is to only allow a snapshot
  range for a specific pre-release with the understanding and a warning that
  no compatibility between snapshot versions is guaranteed. For example:</p>

  <pre>version: 2.0.0-b.1.z
depends: libprint [3.0.0-b.2.1 3.0.0-b.3)</pre>

  <h1 id="module-bin">13 <code>bin</code> Module</h1>

  <p><span class="note">This chapter is a work in progress and is
  incomplete.</span></p>

  <h2 id="module-bin-target-types">13.1 Binary Target Types</h2>

  <p>The following listing shows the hierarchy of the target types defined by
  the <code>bin</code> module while the following sections describe each
  target type in detail (<code>target{}</code> and <code>file{}</code> are
  standard target types defined by the <code>build2</code> core; see <a
  href="#targets-types">Target Types</a> for details).</p>

  <pre>                 target----------------.
                   |                   |
                  ...                  |
                   |                   |
 .---------------file------------.    lib
 |      |      |     |     |     |    libul
 |    libue  obje  bmie  hbmie  def   obj
liba  libua  obja  bmia  hbmia        bmi
libs  libus  objs  bmis  hbmis        hbmi</pre>

  <h3 id="module-bin-target-types-lib">13.1.1 <code>lib{}</code>,
  <code>liba{}</code>, <code>libs{}</code></h3>

  <p>The <code>liba{}</code> and <code>libs{}</code> target types represent
  static (archive) and shared libraries, respectively.</p>

  <p>The <code>lib{}</code> target type is a group with the
  <code>liba{}</code> and/or <code>libs{}</code> members. A rule that
  encounters a <code>lib{}</code> prerequisite may pick a member appropriate
  for the target being built or it may build all the members according to the
  <code>bin.lib</code> variable. See <a href="#intro-lib">Library Exportation
  and Versioning</a> for background.</p>

  <p>The <code>lib*{}</code> file extensions are normally automatically
  assigned by the matching rules based on the target platform.</p>

  <h3 id="module-bin-target-types-libu">13.1.2 <code>libul{}</code>,
  <code>libue{}</code>, <code>libua{}</code>, <code>libus{}</code></h3>

  <p>The <code>libu*{}</code> target types represent utility libraries.
  Utility libraries are static libraries with object files appropriate for
  linking an executable (<code>libue{}</code>), static library
  (<code>libua{}</code>), or shared library (<code>libus{}</code>). Where
  possible, utility libraries are built in the "thin archive" mode.</p>

  <p>The <code>libul{}</code> target type is a group with the
  <code>libua{}</code> and/or <code>libus{}</code> members. A rule that
  encounters a <code>libul{}</code> prerequisite picks a member appropriate
  for the target being built.</p>

  <p>The <code>libu*{}</code> file extensions are normally automatically
  assigned by the matching rules based on the target platform.</p>

  <h3 id="module-bin-target-types-obj">13.1.3 <code>obj{}</code>,
  <code>obje{}</code>, <code>obja{}</code>, <code>objs{}</code></h3>

  <p>The <code>obj*{}</code> target types represent object files appropriate
  for linking an executable (<code>obje{}</code>), static library
  (<code>obja{}</code>), or shared library (<code>objs{}</code>).</p>

  <div class="note">
  <p>In <code>build2</code> we use distinct object files for the three types
  of binaries (executable, static library, and shared library). The
  distinction between static and shared libraries is made to accommodate build
  differences such as the need for position-independent code
  (<code>-fPIC</code>) in shared libraries. While in most cases the same
  object file can be used for executables and static libraries, they are kept
  separate for consistency and generality.</p>
  </div>

  <p>The <code>obj{}</code> target type is a group with the
  <code>obje{}</code>, and/or <code>obja{}</code>, and/or <code>objs{}</code>
  members. A rule that encounters an <code>obj{}</code> prerequisite picks a
  member appropriate for the target being built.</p>

  <p>The <code>obj*{}</code> file extensions are normally automatically
  assigned by the matching rules based on the target platform.</p>

  <h3 id="module-bin-target-types-bmi">13.1.4 <code>bmi{}</code>,
  <code>bmie{}</code>, <code>bmia{}</code>, <code>bmis{}</code></h3>

  <p>The <code>bmi*{}</code> target types represent binary module interfaces
  (BMI) for C++20 named modules appropriate for linking an executable
  (<code>bmie{}</code>), static library (<code>bmia{}</code>), or shared
  library (<code>bmis{}</code>).</p>

  <p>The <code>bmi{}</code> target type is a group with the
  <code>bmie{}</code>, and/or <code>bmia{}</code>, and/or <code>bmis{}</code>
  members. A rule that encounters an <code>bmi{}</code> prerequisite picks a
  member appropriate for the target being built.</p>

  <p>The <code>bmi*{}</code> file extensions are normally automatically
  assigned by the matching rules based on the target platform.</p>

  <h3 id="module-bin-target-types-hbmi">13.1.5 <code>hbmi{}</code>,
  <code>hbmie{}</code>, <code>hbmia{}</code>, <code>hbmis{}</code></h3>

  <p>The <code>hbmi*{}</code> target types represent binary module interfaces
  (BMI) for C++20 header units appropriate for linking an executable
  (<code>hbmie{}</code>), static library (<code>hbmia{}</code>), or shared
  library (<code>hbmis{}</code>).</p>

  <p>The <code>hbmi{}</code> target type is a group with the
  <code>hbmie{}</code>, and/or <code>hbmia{}</code>, and/or
  <code>hbmis{}</code> members. A rule that encounters an <code>hbmi{}</code>
  prerequisite picks a member appropriate for the target being built.</p>

  <p>The <code>hbmi*{}</code> file extensions are normally automatically
  assigned by the matching rules based on the target platform.</p>

  <h3 id="module-bin-target-types-def">13.1.6 <code>def{}</code></h3>

  <p>The <code>def{}</code> target type represents Windows module definition
  files and has the fixed default extension <code>.def</code>.</p>

  <h1 id="module-cc">14 <code>cc</code> Module</h1>

  <p><span class="note">This chapter is a work in progress and is
  incomplete.</span></p>

  <p>This chapter describes the <code>cc</code> build system module which
  provides the common compilation and linking support for C-family
  languages.</p>

  <h2 id="cc-config">14.1 C-Common Configuration Variables</h2>

  <pre>config.c
config.cxx
  cc.id

  cc.target
  cc.target.cpu
  cc.target.vendor
  cc.target.system
  cc.target.version
  cc.target.class

config.cc.poptions
  cc.poptions

config.cc.coptions
  cc.coptions

config.cc.loptions
  cc.loptions

config.cc.aoptions
  cc.aoptions

config.cc.libs
  cc.libs

config.cc.internal.scope
  cc.internal.scope

config.cc.reprocess
  cc.reprocess

config.cc.pkgconfig.sysroot</pre>

  <p>Note that the compiler mode options are "cross-hinted" between
  <code>config.c</code> and <code>config.cxx</code> meaning that if we specify
  one but not the other, mode options, if any, will be added to the absent.
  This may or may not be the desired behavior, for example:</p>

  <pre># Ok: config.c="gcc -m32"
$ b config.cxx="g++ -m32"

# Not OK: config.c="clang -stdlib=libc++"
$ b config.cxx="clang++ -stdlib=libc++"</pre>

  <h2 id="cc-target-types">14.2 C-Common Target Types</h2>

  <p>The following listing shows the hierarchy of the target types defined by
  the <code>cc</code> module while the following sections describe each target
  type in detail (<code>file{}</code> is a standard target type defined by the
  <code>build2</code> core; see <a href="#targets-types">Target Types</a> for
  details). Every <code>cc</code>-based module (such as <code>c</code> and
  <code>cxx</code>) will have these common target types defined in addition to
  the language-specific ones.</p>

  <pre>.--file--.
|        |
h       pc
         |
        pca
        pcs</pre>

  <div class="note">
  <p>While the <code>h{}</code> target type represents a C header file, there
  is hardly a C-family compilation without a C header inclusion. As a result,
  this target types is defined by all <code>cc</code>-based modules.</p>
  </div>

  <p>For the description of the <code>h{}</code> target type refer to <a
  href="#c-target-types-c"><code>c{}</code>, <code>h{}</code></a> in the C
  module documentation.</p>

  <h3 id="cc-target-types-pc">14.2.1 <code>pc{}</code>, <code>pca{}</code>,
  <code>pcs{}</code></h3>

  <p>The <code>pc*{}</code> target types represent <code>pkg-config</code>
  files. The <code>pc{}</code> target type represents the common file and has
  the fixed default extension <code>.pc</code>. The <code>pca{}</code> and
  <code>pcs{}</code> target types represent the static and shared files and
  have the fixed default extensions <code>.static.pc</code> and
  <code>.shared.pc</code>, respectively. See <a
  href="#cc-import-installed">Importation of Installed Libraries</a> for
  background.</p>

  <h2 id="cc-internal-scope">14.3 Compilation Internal Scope</h2>

  <div class="note">
  <p>While this section uses the <code>cxx</code> module and C++ compilation
  as an example, the same functionality is available for C compilation &#8211;
  simply replace <code>cxx</code> with <code>c</code> in the module and
  variable names.</p>
  </div>

  <p>The <code>cxx</code> module has a notion of a project's internal scope.
  During compilation of a project's C/C++ translation units a header search
  path (<code>-I</code>) exported by a library that is outside of the internal
  scope is considered external and, if supported by the compiler, the
  corresponding <code>-I</code> option is translated to an appropriate
  "external header search path" option (<code>-isystem</code> for GCC/Clang,
  <code>/external:I</code> for MSVC 16.10 and later). In particular, this
  suppresses compiler warnings in such external headers
  (<code>/external:W0</code> is automatically added unless a custom
  <code>/external:Wn</code> is specified).</p>

  <div class="note">
  <p>While the aim of this functionality is to control warnings in external
  libraries, the underlying mechanisms currently provided by compilers have
  limitations and undesirable side effects. In particular,
  <code>-isystem</code> paths are searched after <code>-I</code> so
  translating <code>-I</code> to <code>-isystem</code> alters the search
  order. This should normally be harmless when using a development build of a
  library but may result in a change of semantics for installed libraries.
  Also, marking the search path as system has additional (to warning
  suppression) effects, see <a
  href="https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html">System
  Headers</a> in the GCC documentation for details. On the MSVC side,
  <code>/external:W0</code> currently does not suppress some warnings (refer
  to the MSVC documentation for details).</p>

  <p>Another issue is warnings in template instantiations. Each such warning
  could be either due to a (potential) issue in the template itself or due to
  the template arguments we are instantiating it with. By default, all such
  warnings are suppressed and there is currently no way to change this with
  GCC/Clang <code>-isystem</code>. While MSVC provides
  <code>/external:templates-</code>, it cannot be applied on the library by
  library basis, only globally for the entire compilation. See MSVC
  <code>/external:templates-</code> documentation for more background on this
  issue.</p>
  </div>

  <div class="note">
  <p>In the future this functionality will be extended to side-building BMIs
  for external module interfaces and header units.</p>
  </div>

  <p>The internal scope can be specified by the project with the
  <code>cxx.internal.scope</code> variable and overridden by the user with the
  <code>config.cxx.internal.scope</code> variable. Note that
  <code>cxx.internal.scope</code> must be specified before loading the
  <code>cxx</code> module (<code>cxx.config</code>, more precisely) and after
  which it contains the effective value (see below). For example:</p>

  <pre># root.build

cxx.std = latest
cxx.internal.scope = current

using cxx</pre>

  <p>Valid values for <code>cxx.internal.scope</code> are:</p>

  <pre>current  -- current root scope (where variable is assigned)
base     -- target's base scope
root     -- target's root scope
bundle   -- target's bundle amalgamation
strong   -- target's strong amalgamation
weak     -- target's weak amalgamation
global   -- global scope (everything is internal)</pre>

  <p>Valid values for <code>config.cxx.internal.scope</code> are the same
  except for <code>current</code>.</p>

  <p>Note also that there are <code>[config.]cc.internal.scope</code>
  variables that can be used to specify the internal scope for all the
  <code>cc</code>-based modules.</p>

  <p>The project's effective internal scope is chosen based on the following
  priority list:</p>

  <ol>
  <li><code>config.cxx.internal.scope</code></li>

  <li><code>config.cc.internal.scope</code></li>

  <li>effective scope from bundle amalgamation</li>

  <li><code>cxx.internal.scope</code></li>

  <li><code>cc.internal.scope</code></li>
  </ol>

  <p>In particular, item #3 allows an amalgamation that bundles a project to
  override its internal scope.</p>

  <div class="note">
  <p>If no <code>*.internal.scope</code> is specified by the project, user, or
  bundle, then this functionality is disabled and all libraries are treated as
  internal regardless of their location.</p>

  <p>While it may seem natural to have this enabled by default, the
  limitations and side effects of the underlying mechanisms as well as cases
  where it would be undesirable (such as in separate <code>*-tests</code>
  projects, see below) all suggest that explicit opt-in is probably the
  correct choice.</p>
  </div>

  <p>The recommended value for a typical project is <code>current</code>,
  meaning that only headers inside the project will be considered internal.
  The <code>tests</code> subproject, if present, will inherit its value from
  the project (which acts as a bundle amalgamation), unless it is being built
  out of source (for example, to test an installed library).</p>

  <p>A project can also whitelist specific libraries using the
  <code>cxx.internal.libs</code> variable. If a library target name (that is,
  the name inside <code>lib{}</code>) matches any of the wildcard patterns
  listed in this variable, then the library is considered internal regardless
  of its location. For example (notice that the pattern is quoted):</p>

  <pre># root.build

cxx.std = latest
cxx.internal.scope = current
cxx.internal.libs = foo 'bar-*'

using cxx</pre>

  <p>Note that this variable should also be set before loading the
  <code>cxx</code> module and there is the common
  <code>cc.internal.libs</code> equivalent. However, there are no
  <code>config.*</code> versions nor the override by the bundle amalgamation
  semantics.</p>

  <p>Typically you would want to whitelist libraries that are developed
  together but reside in separate build system projects. In particular, a
  separate <code>*-tests</code> project for a library should whitelist the
  library being tested if the internal scope functionality is in use. Another
  reason to whitelist is to catch warnings in instantiations of templates that
  belong to a library that is otherwise warning-free (see the MSVC
  <code>/external:templates-</code> option for background).</p>

  <p>Note also that if multiple libraries are installed into the same location
  (or otherwise share the same header search paths, for example, as a family
  of libraries), then the whitelist may not be effective.</p>

  <h2 id="cc-auto-symexport">14.4 Automatic DLL Symbol Exporting</h2>

  <p>The <code>bin.def</code> module (automatically loaded by the
  <code>c</code> and <code>cxx</code> modules for the
  <code>*-win32-msvc</code> targets) provides a rule for generating
  symbol-exporting <code>.def</code> files. This allows automatically
  exporting all symbols for all the Windows targets/compilers using the
  following arrangement (showing for <code>cxx</code> in this example):</p>

  <pre>lib{foo}: libul{foo}: {hxx cxx}{**} ...

libs{foo}: def{foo}: include = ($cxx.target.system == 'win32-msvc')
def{foo}: libul{foo}

if ($cxx.target.system == 'mingw32')
  cxx.loptions += -Wl,--export-all-symbols</pre>

  <p>That is, we use the <code>.def</code> file approach for MSVC (including
  when building with Clang) and the built-in support
  (<code>--export-all-symbols</code>) for MinGW.</p>

  <div class="note">
  <p>You will likely also want to add the generated <code>.def</code> file (or
  the blanket <code>*.def</code>) to your <code>.gitignore</code> file.</p>
  </div>

  <p>Note that it is also possible to use the <code>.def</code> file approach
  for MinGW. In this case we need to explicitly load the <code>bin.def</code>
  module (which should be done after loading <code>c</code> or
  <code>cxx</code>) and can use the following arrangement:</p>

  <pre># root.build

using cxx

if ($cxx.target.class == 'windows')
  using bin.def</pre>

  <pre>lib{foo}: libul{foo}: {hxx cxx}{**} ...

libs{foo}: def{foo}: include = ($cxx.target.class == 'windows')
def{foo}: libul{foo}</pre>

  <p>Note also that this only deals with exporting of the symbols from a DLL.
  In order to work, code that uses such a DLL should be able to import the
  symbols without explicit <code>__declspec(dllimport)</code> declarations.
  This works thanks to the symbol auto-importing support in Windows linkers.
  Note, however, that auto-importing only works for functions and not for
  global variables.</p>

  <h2 id="cc-import-installed">14.5 Importation of Installed Libraries</h2>

  <p>As discussed in <a href="#intro-import">Target Importation</a>, searching
  for installed C/C++ libraries is seamlessly integrated into the general
  target importation mechanism. This section provides more details on the
  installed library search semantics and <code>pkg-config</code> integration.
  These details can be particularly useful when dealing with libraries that
  were not built with <code>build2</code> and which often use idiosyncratic
  <code>pkg-config</code> file names.</p>

  <p>The <code>cc</code>-based modules use the common installed library search
  implementation with the following semantics. To illustrate the finer points,
  we assume the following import:</p>

  <pre>import libs = libbar%lib{Xfoo}</pre>

  <ol>
  <li>First, the ordered list of library search directories is obtained by
  combining two lists: the lists of the compiler's system library search
  directories (extracted, for example, with <code>-print-search-dirs</code>
  GCC/Clang options) and the list of user library search directories
  (specified, for example, with the <code>-L</code> options in
  <code>*.loptions</code>).

  <p>The key property of this combined list is that it matches the search
  semantics that would be used by the compiler to find libraries specified
  with the <code>-l</code> option during linking.</p></li>

  <li>Given the list obtained in the previous step, a library binary (shared
  and/or static library) is searched for in the correct order and using the
  target platform-appropriate library prefix and extension (for example,
  <code>lib</code> prefix and the <code>.so</code>/<code>.a</code> extensions
  if targeting Linux).

  <p>For example (continuing with the above import and assuming Linux), each
  directory will be checked for the presence of <code>libXfoo.so</code> and
  <code>libXfoo.a</code> (where the <code>Xfoo</code> stem is the imported
  target name).</p>

  <p>If only a shared or static binary is found in a given directory, no
  further directories are checked for the missing variant. Instead, the
  missing variant is assumed to be unavailable.</p>

  <p>If neither a shared nor static library is found in a given directory,
  then it is also checked for the presence of the corresponding
  <code>pkg-config</code> file as in the following step. If such a file is
  found, then the library is assumed to be <i>binless</i> (header-only,
  etc).</p></li>

  <li>If a static and/or shared library is found (or if looking for a binless
  library), the corresponding <code>pkg-config</code> subdirectory (normally
  just <code>pkgconfig/</code>) is searched for the library's <code>.pc</code>
  file.

  <p>More precisely, we first look for the <code>.static.pc</code> file for a
  static library and for the <code>.shared.pc</code> file for a shared library
  falling back to the common <code>.pc</code> if they don't exist.</p>

  <div class="note">
  <p>It is often required to use different options for consuming static and
  shared libraries. While there is the <code>Libs.private</code> and
  <code>Cflags.private</code> mechanism in <code>pkg-config</code>, its
  semantics is to append options to <code>Libs</code> and <code>Cflags</code>
  rather than to provide alternative options. And often the required semantics
  is to provide different options for static and shared libraries, such as to
  provide a macro which indicates whether linking static or shared in order to
  setup symbol exporting.</p>

  <p>As a result, in <code>build2</code> we produce separate <code>.pc</code>
  files for static and shared libraries in addition to the "best effort"
  common <code>.pc</code> file for compatibility with other build systems.
  Similarly, when consuming a library we first look for the
  <code>.static.pc</code> and <code>.shared.pc</code> files falling back to
  the common <code>.pc</code> if they are not available.</p>
  </div>

  <p>To deal with idiosyncrasies in <code>pkg-config</code> file names, the
  following base names are tried in order, where <code><i>name</i></code> is
  the imported target name (<code>Xfoo</code> in the above import),
  <code><i>proj</i></code> is the imported project name (<code>libbar</code>
  in the above import), and <code><i>ext</i></code> is one of the
  above-mentioned <code>pkg-config</code> extensions (<code>static.pc</code>,
  <code>shared.pc</code>, or <code>pc</code>). The concrete name tried for the
  above import is shown in parenthesis as an example.</p>

  <ol>
  <li><code>lib<i>name</i>.<i>ext</i></code> (<code>libXfoo.pc</code>)</li>

  <li><code><i>name</i>.<i>ext</i></code> (<code>Xfoo.pc</code>)</li>

  <li>lowercase <code>lib<i>name</i>.<i>ext</i></code>
  (<code>libxfoo.pc</code>)</li>

  <li>lowercase <code><i>name</i>.<i>ext</i></code>
  (<code>xfoo.pc</code>)</li>

  <li><code><i>proj</i>.<i>ext</i></code> (<code>libbar.pc</code>; this test
  is omitted if not project-qualified)</li>
  </ol></li>
  </ol>

  <p>In particular, the last try (for <code><i>proj</i>.<i>ext</i></code>)
  serves as an escape hatch for cases where the <code>.pc</code> file name
  does not have anything to do with the names of library binaries. The
  canonical example of this is <code>zlib</code> which names its library
  binaries <code>libz.so</code>/<code>libz.a</code> while its <code>.pc</code>
  file &#8211; <code>zlib.pc</code>. To be able to import <code>zlib</code>
  that was not built with <code>build2</code>, we have to use the following
  import:</p>

  <pre>import libs = zlib%lib{z}</pre>

  <p>Note also that these complex rules (which are unfortunately necessary to
  deal with the lack of any consistency in <code>.pc</code> file naming) can
  sometimes produce surprising interactions. For example, it may appear that a
  clearly incorrect import nevertheless appears to somehow work, as in the
  following example:</p>

  <pre>import libs = zlib%lib{znonsense}</pre>

  <p>What happens here is that while no library binary is found,
  <code>zlib.pc</code> is found and as a result the library ends up being
  considered binless with the <code>-lz</code> (that is found in the
  <code>Libs</code> value of <code>zlib.pc</code>) treated as a prerequisite
  library, resolved using the above algorithm, and linked. In other words, in
  this case we end up with a binless library <code>lib{znonsense}</code> that
  depends on <code>lib{z}</code> instead of a single <code>lib{z}</code>
  library.</p>

  <h3 id="cc-import-installed-sysroot">14.5.1 Rewriting Installed Libraries
  System Root (sysroot)</h3>

  <p>Sometimes the installed libraries are moved to a different location after
  the installation. This is especially common in embedded development where
  the code is normally cross-compiled and the libraries for the target
  platform are placed into a host directory, called system root or
  <i>sysroot</i>, that doesn't match where these libraries were originally
  installed to. For example, the libraries might have been installed into
  <code>/usr/</code> but on the host machine they may reside in
  <code>/opt/target/usr/</code>. In this example, <code>/opt/target/</code> is
  the sysroot.</p>

  <p>While such relocations usually do not affect the library headers or
  binaries, they do break the <code>pkg-config</code>'s <code>.pc</code> files
  which often contain <code>-I</code> and <code>-L</code> options with
  absolute paths. Continue with the above example, a <code>.pc</code> file as
  originally installed may contain <code>-I/usr/include</code> and
  <code>-L/usr/lib</code> while now, that the libraries have been relocated to
  <code>/opt/target/</code>, they somehow need to be adjusted to
  <code>-I/opt/target/usr/include</code> and
  <code>-L/opt/target/usr/lib</code>.</p>

  <p>While it is possible (and perhaps correct) to accomplish this by fixing
  the <code>.pc</code> files to match the new location, it is not always
  possible or easy. As a result, <code>build2</code> provides a mechanism for
  automatically adjusting the system root in the <code>-I</code> and
  <code>-L</code> options extracted from <code>.pc</code> files.</p>

  <div class="note">
  <p>This functionality is roughly equivalent to that provided with the
  <code>PKG_CONFIG_SYSROOT_DIR</code> environment variable by the
  <code>pkg-config</code> utility.</p>
  </div>

  <p>Specifically, the <code>config.cc.pkgconfig.sysroot</code> variable can
  be used to specify an alternative system root. When specified, all absolute
  paths in the <code>-I</code> and <code>-L</code> options that are not
  already in this directory will be rewritten to start with this sysroot.</p>

  <div class="note">
  <p>Note that this mechanism is a workaround rather than a proper solution
  since it is limited to the <code>-I</code> and <code>-L</code> options. In
  particular, it does not handle any other options that may contain absolute
  paths nor <code>pkg-config</code> variables that may be queried.</p>

  <p>As a result, it should only be used for dealing with issues in
  third-party <code>.pc</code> files that do not handle relocation (for
  example, using the <code>${pcfiledir}</code> built-in
  <code>pkg-config</code> variable). In particular, for
  <code>build2</code>-generated <code>.pc</code> files a <a
  href="#install-reloc">relocatable installation</a> should be used
  instead.</p>
  </div>

  <h2 id="cc-gcc">14.6 GCC Compiler Toolchain</h2>

  <p>The GCC compiler id is <code>gcc</code>.</p>

  <h2 id="cc-clang">14.7 Clang Compiler Toolchain</h2>

  <p>The vanilla Clang compiler id is <code>clang</code> (including when
  targeting the MSVC runtime), Apple Clang compiler id is
  <code>clang-apple</code>, and Clang's <code>cl</code> compatibility driver
  (<code>clang-cl</code>) id is <code>msvc-clang</code>.</p>

  <h3 id="cc-clang-msvc">14.7.1 Clang Targeting MSVC</h3>

  <p>There are two common ways to obtain Clang on Windows: bundled with the
  MSVC installation or as a separate installation. If you are using the
  separate installation, then the Clang compiler is most likely already in the
  <code>PATH</code> environment variable. Otherwise, if you are using Clang
  that is bundled with MSVC, the <code>cc</code> module will attempt various
  search strategies described below. Note, however, that in both cases once
  the Clang compiler binary located, the mode (32 or 64-bit) and the rest of
  the environment (locations of binary utilities as well as the system headers
  and libraries) are obtained by querying Clang.</p>

  <div class="note">
  <p>Normally, if Clang is invoked from one of the Visual Studio command
  prompts, then it will use the corresponding Visual Studio version and
  environment (it is, however, still up to you to match the mode with the
  <code>-m32</code>/<code>-m64</code> options, if necessary). Otherwise, Clang
  will try to locate the latest version of Visual Studio and Platform SDK and
  use that (in this case it matches the environment to the
  <code>-m32</code>/<code>-m64</code> options).  Refer to Clang documentation
  for details.</p>
  </div>

  <p>If you specify the compiler as just <code>config.c=clang</code> or
  <code>config.cxx=clang++</code> and it is found in the <code>PATH</code>
  environment variable or if you specify it as an absolute path, then the
  <code>cc</code> module will use that.</p>

  <p>Otherwise, if you are building from one of the Visual Studio development
  command prompts, the <code>cc</code> module will look for the corresponding
  bundled Clang (<code>%VCINSTALLDIR%\Tools\Llvm\bin</code>).</p>

  <p>Finally, the <code>cc</code> module will attempt to locate the latest
  installed version of Visual Studio and look for a bundled Clang in
  there.</p>

  <p>The default mode (32 or 64-bit) depends on the Clang configuration and
  can be overridden with the <code>-m32</code>/<code>-m64</code> options. For
  example:</p>

  <pre>> b "config.cxx=clang++ -m64"</pre>

  <p>The default MSVC runtime selected by the <code>cc</code> module is
  multi-threaded shared (the <code>/MD</code> option in <code>cl</code>).
  Unfortunately, the Clang driver does not yet provide anything equivalent to
  the <code>cl</code> <code>/M*</code> options (see <a
  href="https://bugs.llvm.org/show_bug.cgi?id=33273">Clang bug #33273</a>) and
  selection of an alternative runtime has to be performed manually:</p>

  <pre>> rem /MD  - multi-threaded shared (default)
> rem
> b "config.cxx=clang++ -nostdlib -D_MT -D_DLL" ^
    config.cc.libs=/DEFAULTLIB:msvcrt

> rem /MDd - multi-threaded debug shared
> rem
> b "config.cxx=clang++ -nostdlib -D_MT -D_DLL -D_DEBUG" ^
    config.cc.libs=/DEFAULTLIB:msvcrtd

> rem /MT  - multi-threaded static
> rem
> b "config.cxx=clang++ -nostdlib -D_MT" ^
    config.cc.libs=/DEFAULTLIB:libcmt

> rem /MTd - multi-threaded debug static
> rem
> b "config.cxx=clang++ -nostdlib -D_MT -D_DEBUG" ^
    config.cc.libs=/DEFAULTLIB:libcmtd</pre>

  <p>By default the MSVC's binary utilities (<code>link</code> and
  <code>lib</code>) are used when compiling with Clang. It is, however,
  possible to use LLVM's versions instead, for example:</p>

  <pre>> b config.cxx=clang++     ^
    config.bin.ld=lld-link ^
    config.bin.ar=llvm-lib</pre>

  <p>In particular, one benefit of using <code>llvm-lib</code> is support for
  thin archives which, if available, is automatically enabled for utility
  libraries.</p>

  <div class="note">
  <p>While there is basic support for Clang's <code>cl</code> compatibility
  driver (<code>clang-cl</code>), its use is not recommended. This driver is a
  very thin wrapper over the standard Clang interface that does not always
  recreate the <code>cl</code>'s semantics exactly. Specifically, its
  diagnostics in the <code>/showIncludes</code> mode does not match that of
  <code>cl</code> in the presence of missing headers. As a result,
  <code>clang-cl</code>'s use, if any, should be limited to projects that do
  not have auto-generated headers.</p>

  <p>If you need to link with other projects that use <code>clang-cl</code>,
  then the recommended approach is to discover any additional <code>cc1</code>
  options passed by <code>clang-cl</code> by comparing the <code>-v</code>
  output of a test compilation with <code>clang-cl</code> and
  <code>clang</code>/<code>clang++</code> and then passing them explicitly to
  <code>clang</code>/<code>clang++</code>, potentially prefixed with
  <code>-Xclang</code>. For example:</p>

  <pre>b "config.cxx=clang++ -Xclang -fms-volatile ..."</pre>

  <p>Relevant additional options that are passed by <code>clang-cl</code> at
  the time of this writing:</p>

  <pre>-fno-strict-aliasing
-fstack-protector-strong
-Xclang -fms-volatile
-ffunction-sections</pre>
  </div>

  <h2 id="cc-msvc">14.8 MSVC Compiler Toolchain</h2>

  <p>The Microsoft VC (MSVC) compiler id is <code>msvc</code>.</p>

  <p>There are several ways to specify the desired MSVC compiler and mode (32
  or 64-bit) as well as the corresponding environment (locations of binary
  utilities as well as the system headers and libraries).</p>

  <div class="note">
  <p>Unlike other compilers, MSVC compiler (<code>cl</code>) binaries are
  target-specific, that is, there are no <code>-m32</code>/<code>-m64</code>
  options nor something like the <code>/MACHINE</code> option available in
  <code>link</code>.</p>
  </div>

  <p>If the compiler is specified as just <code>cl</code> in
  <code>config.{c,cxx</code>} and it is found in the <code>PATH</code>
  environment variable, then the <code>cc</code> module assumes the build is
  performed from one of the Visual Studio development command prompts and
  expects the environment (the <code>PATH</code>, <code>INCLUDE</code>, and
  <code>LIB</code> environment variables) to already be setup.</p>

  <p>If, however, <code>cl</code> is not found in <code>PATH</code>, then the
  <code>cc</code> module will attempt to locate the latest installed version
  of Visual Studio and Platform SDK and use that in the 64-bit mode.</p>

  <p>Finally, if the compiler is specified as an absolute path to
  <code>cl</code>, then the <code>cc</code> module will attempt to locate the
  corresponding Visual Studio installation as well as the latest Platform SDK
  and use that in the mode corresponding to the specified <code>cl</code>
  executable. Note that to specify an absolute path to <code>cl</code> (which
  most likely contains spaces) we have to use two levels of quoting:</p>

  <pre>> b "config.cxx='...\VC\Tools\MSVC\14.23.28105\bin\Hostx64\x86\cl'"</pre>

  <div class="note">
  <p>The latter two methods are only available for Visual Studio 15 (2017) and
  later and for earlier versions the development command prompt must be
  used.</p>
  </div>

  <p>The default MSVC runtime selected by the <code>cc</code> module is
  multi-threaded shared (the <code>/MD</code> <code>cl</code> option). An
  alternative runtime can be selected by passing one of the <code>cl</code>
  <code>/M*</code> options, for example:</p>

  <pre>> b "config.cxx=cl /MT"</pre>

  <h1 id="module-c">15 <code>c</code> Module</h1>

  <p><span class="note">This chapter is a work in progress and is
  incomplete.</span></p>

  <p>This chapter describes the <code>c</code> build system module which
  provides the C compilation and linking support. Most of its functionality,
  however, is provided by the <a href="#module-cc"><code>cc</code></a> module,
  a common implementation for the C-family languages.</p>

  <h2 id="c-config">15.1 C Configuration Variables</h2>

  <p>The following listing summarizes the <code>c</code> module configuration
  variables as well as the corresponding module-specific variables that are
  derived from their values. See also <a href="#cc-config">C-Common
  Configuration Variables</a>.</p>

  <pre>config.c
  c.path
  c.mode

config.c.id
  c.id
  c.id.type
  c.id.variant
  c.class

config.c.version
  c.version
  c.version.major
  c.version.minor
  c.version.patch
  c.version.build

config.c.target
  c.target
  c.target.cpu
  c.target.vendor
  c.target.system
  c.target.version
  c.target.class

config.c.std
  c.std

config.c.poptions
  c.poptions

config.c.coptions
  c.coptions

config.c.loptions
  c.loptions

config.c.aoptions
  c.aoptions

config.c.libs
  c.libs

config.c.internal.scope
  c.internal.scope</pre>

  <h2 id="c-target-types">15.2 C Target Types</h2>

  <p>The following listing shows the hierarchy of the target types defined by
  the <code>c</code> module while the following sections describe each target
  type in detail (<code>file{}</code> is a standard target type defined by the
  <code>build2</code> core; see <a href="#targets-types">Target Types</a> for
  details). See also <a href="#cc-target-types">C-Common Target Types</a> for
  target types defined by all the <code>cc</code>-based modules.</p>

  <pre>.--file--.
|   |    |
c   m    S
h</pre>

  <p>The <code>m{}</code> target type represents an Objective-C source file,
  see <a href="c-objc">Objective-C Compilation</a> for details.</p>

  <p>The <code>S{}</code> target type represents an Assembler with C
  Preprocessor file, see <a href="c-as-cpp">Assembler with C Preprocessor
  Compilation</a> for details.</p>

  <h3 id="c-target-types-c">15.2.1 <code>c{}</code>, <code>h{}</code></h3>

  <p>The <code>c{}</code> and <code>h{}</code> target types represent C source
  and header files. They have the default extensions <code>.c</code> and
  <code>.h</code>, respectively, which can be customized with the
  <code>extension</code> variable.</p>

  <h2 id="c-objc">15.3 Objective-C Compilation</h2>

  <p>The <code>c</code> module provides the <code>c.objc</code> submodule
  which can be loaded in order to register the <code>m{}</code> target type
  and enable Objective-C compilation in the <code>C</code> compile rule. Note
  that <code>c.objc</code> must be loaded after the <code>c</code> module and
  while the <code>m{}</code> target type is registered unconditionally,
  compilation is only enabled if the C compiler supports Objective-C for the
  target platform. Typical usage:</p>

  <pre># root.build
#
using c
using c.objc</pre>

  <pre># buildfile
#
lib{hello}: {h c}{*}
lib{hello}: m{*}: include = ($c.target.class  == 'macos')</pre>

  <p>Note also that while there is support for linking Objective-C executables
  and libraries, this is done using the C compiler driver and no attempt is
  made to automatically link any necessary Objective-C runtime library (such
  as <code>-lobjc</code>).</p>

  <h2 id="c-as-cpp">15.4 Assembler with C Preprocessor Compilation</h2>

  <p>The <code>c</code> module provides the <code>c.as-cpp</code> submodule
  which can be loaded in order to register the <code>S{}</code> target type
  and enable Assembler with C Preprocessor compilation in the <code>C</code>
  compile rule. Note that <code>c.as-cpp</code> must be loaded after the
  <code>c</code> module and while the <code>S{}</code> target type is
  registered unconditionally, compilation is only enabled if the C compiler
  supports Assembler with C Preprocessor compilation. Typical usage:</p>

  <pre># root.build
#
using c
using c.as-cpp</pre>

  <pre># buildfile
#
exe{hello}: {h c}{* -hello.c}

# Use C implementation as a fallback if no assembler.
#
assembler = ($c.class == 'gcc' &amp;&amp; $c.target.cpu == 'x86_64')

exe{hello}: S{hello}: include = $assembler
exe{hello}: c{hello}: include = (!$assembler)</pre>

  <pre>/* hello.S
 */
#ifndef HELLO_RESULT
#  define HELLO_RESULT 0
#endif

text

.global hello
hello:
  /* ... */
  movq $HELLO_RESULT, %rax
  ret

#ifdef __ELF__
.section .note.GNU-stack, "", @progbits
#endif</pre>

  <p>The default file extension for the <code>S{}</code> target type is
  <code>.S</code> (capital) but that can be customized using the standard
  mechanisms. For example:</p>

  <pre># root.build
#
using c
using c.as-cpp

h{*}: extension = h
c{*}: extension = c
S{*}: extension = sx</pre>

  <p>Note that <code>*.coptions</code> are passed to the C compiler when
  compiling Assembler with C Preprocessor files because compile options may
  cause additional preprocessor macros to be defined. Plus, some of them (such
  as <code>-g</code>) are passed (potentially translated) to the underlying
  assembler. To pass additional options when compiling Assembler files use
  <code>c.poptions</code> and <code>c.coptions</code>. For example (continuing
  with the previous example):</p>

  <pre>if $assembler
{
  obj{hello}:
  {
    c.poptions += -DHELLO_RESULT=1
    c.coptions += -Wa,--no-pad-sections
  }
}</pre>

  <h2 id="c-predefs">15.5 C Compiler Predefined Macro Extraction</h2>

  <p>The <code>c</code> module provides the <code>c.predefs</code> submodule
  which can be loaded in order to register a rule that generates a C header
  with predefined compiler macros. Note that the <code>c.predefs</code> module
  must be loaded after the <code>c</code> module and the rule will only match
  with an explicit rule hint. Typical usage:</p>

  <pre># root.build
#
using c
using c.predefs</pre>

  <pre># buildfile
#
[rule_hint=c.predefs] h{predefs}:</pre>

  <p>Note also that the MSVC compiler only supports the predefined macro
  extraction starting from Visual Studio 2019 (16.0; <code>cl.exe</code>
  version 19.20). If support for earlier versions is required, then you will
  need to provide a fallback implementation appropriate for your project. For
  example:</p>

  <pre>[rule_hint=c.predefs] h{predefs}:
% update
if ($c.id == 'msvc' &amp;&amp; \
    ($c.version.major &lt; 19 || \
     ($c.version.major == 19 &amp;&amp; $c.version.minor &lt; 20)))
{{
  diag c-predefs $>

  cat &lt;&lt;EOF >$path($>)
  #define _WIN32
  EOF
}}</pre>

  <h1 id="module-cxx">16 <code>cxx</code> Module</h1>

  <p><span class="note">This chapter is a work in progress and is
  incomplete.</span></p>

  <p>This chapter describes the <code>cxx</code> build system module which
  provides the C++ compilation and linking support. Most of its functionality,
  however, is provided by the <a href="#module-cc"><code>cc</code></a> module,
  a common implementation for the C-family languages.</p>

  <h2 id="cxx-config">16.1 C++ Configuration Variables</h2>

  <p>The following listing summarizes the <code>cxx</code> module
  configuration variables as well as the corresponding module-specific
  variables that are derived from their values. See also <a
  href="#cc-config">C-Common Configuration Variables</a>.</p>

  <pre>config.cxx
  cxx.path
  cxx.mode

config.cxx.id
  cxx.id
  cxx.id.type
  cxx.id.variant
  cxx.class

config.cxx.version
  cxx.version
  cxx.version.major
  cxx.version.minor
  cxx.version.patch
  cxx.version.build

config.cxx.target
  cxx.target
  cxx.target.cpu
  cxx.target.vendor
  cxx.target.system
  cxx.target.version
  cxx.target.class

config.cxx.std
  cxx.std

config.cxx.poptions
  cxx.poptions

config.cxx.coptions
  cxx.coptions

config.cxx.loptions
  cxx.loptions

config.cxx.aoptions
  cxx.aoptions

config.cxx.libs
  cxx.libs

config.cxx.internal.scope
  cxx.internal.scope

config.cxx.translate_include
  cxx.translate_include</pre>

  <h2 id="cxx-target-types">16.2 C++ Target Types</h2>

  <p>The following listing shows the hierarchy of the target types defined by
  the <code>cxx</code> module while the following sections describe each
  target type in detail (<code>file{}</code> is a standard target type defined
  by the <code>build2</code> core; see <a href="#targets-types">Target
  Types</a> for details). See also <a href="#cc-target-types">C-Common Target
  Types</a> for target types defined by all the <code>cc</code>-based
  modules.</p>

  <pre> .--file--.
 |        |
cxx      mm
hxx
ixx
txx
mxx</pre>

  <p>The <code>mm{}</code> target type represents an Objective-C++ source
  file, see <a href="cxx-objcxx">Objective-C++ Compilation</a> for
  details.</p>

  <h3 id="cxx-target-types-cxx">16.2.1 <code>cxx{}</code>, <code>hxx{}</code>,
  <code>ixx{}</code>, <code>txx{}</code>, <code>mxx{}</code></h3>

  <p>The <code>cxx{}</code>, <code>hxx{}</code>, <code>ixx{}</code>,
  <code>txx{}</code>, and <code>mxx{}</code> target types represent C++
  source, header, inline, template, and module interface files. They have the
  default extensions <code>.cxx</code>, <code>.hxx</code>, <code>.ixx</code>,
  <code>.txx</code>, and <code>.mxx</code>, respectively, which can be
  customized with the <code>extension</code> variable. For example (normally
  done in <code>root.build</code>):</p>

  <pre>using cxx

cxx{*}: extension = cpp
hxx{*}: extension = hpp
mxx{*}: extension = cppm</pre>

  <h2 id="cxx-modules">16.3 C++ Modules Support</h2>

  <p>This section describes the build system support for C++ modules.</p>

  <h3 id="cxx-modules-intro">16.3.1 Modules Introduction</h3>

  <p>The goal of this section is to provide a practical introduction to C++
  Modules and to establish key concepts and terminology. You can skip directly
  to <a href="#cxx-modules-build">Building Modules</a> if you are already
  familiar with this topic.</p>

  <p>A pre-modules C++ program or library consists of one or more
  <i>translation units</i> which are customarily referred to as C++ source
  files. Translation units are compiled to <i>object files</i> which are then
  linked together to form a program or library.</p>

  <p>Let's also recap the difference between an <i>external name</i> and a
  <i>symbol</i>: External names refer to language entities, for example
  classes, functions, and so on. The <i>external</i> qualifier means they are
  visible across translation units.</p>

  <p>Symbols are derived from external names for use inside object files. They
  are the cross-referencing mechanism for linking a program from multiple,
  separately-compiled translation units. Not all external names end up
  becoming symbols and symbols are often <i>decorated</i> with additional
  information, for example, a namespace. We often talk about a symbol having
  to be satisfied by linking an object file or a library that provides it.
  Similarly, duplicate symbol issues may arise if more than one object file or
  library provides the same symbol.</p>

  <p>What is a C++ module? It is hard to give a single but intuitive answer to
  this question.  So we will try to answer it from three different
  perspectives: that of a module consumer, a module producer, and a build
  system that tries to make those two play nice. But we can make one thing
  clear at the outset: modules are a <i>language-level</i> not a
  preprocessor-level mechanism; it is <code>import</code>, not
  <code>#import</code>.</p>

  <p>One may also wonder why C++ modules, what are the benefits? Modules offer
  isolation, both from preprocessor macros and other modules' symbols. Unlike
  headers, modules require explicit exportation of entities that will be
  visible to the consumers. In this sense they are a <i>physical design
  mechanism</i> that forces us to think how we structure our code. Modules
  promise significant build speedups since importing a module, unlike
  including a header, should be essentially free. Modules are also the first
  step to not needing the preprocessor in most translation units. Finally,
  modules have a chance of bringing to mainstream reliable and easy to setup
  distributed C++ compilation, since with modules build systems can make sure
  compilers on the local and remote hosts are provided with identical
  inputs.</p>

  <p>To refer to a module we use a <i>module name</i>, a sequence of
  dot-separated identifiers, for example <code>hello.core</code>. While the
  specification does not assign any hierarchical semantics to this sequence,
  it is customary to refer to <code>hello.core</code> as a submodule of
  <code>hello</code>. We discuss submodules and provide the module naming
  guidelines below.</p>

  <p>From a consumer's perspective, a module is a collection of external
  names, called <i>module interface</i>, that become <i>visible</i> once the
  module is imported:</p>

  <pre>import hello.core;</pre>

  <p>What exactly does <i>visible</i> mean? To quote the standard: <i>An
  import-declaration makes exported declarations [...] visible to name lookup
  in the current translation unit, in the same namespaces and contexts [...].
  [ Note: The entities are not redeclared in the translation unit containing
  the module import declaration. -- end note ]</i> One intuitive way to think
  about this visibility is <i>as if</i> there were only a single translation
  unit for the entire program that contained all the modules as well as all
  their consumers. In such a translation unit all the names would be visible
  to everyone in exactly the same way and no entity would be redeclared.</p>

  <p>This visibility semantics suggests that modules are not a name scoping
  mechanism and are orthogonal to namespaces. Specifically, a module can
  export names from any number of namespaces, including the global namespace.
  While the module name and its namespace names need not be related, it
  usually makes sense to have a parallel naming scheme, as discussed below.
  Finally, the <code>import</code> declaration does not imply any additional
  visibility for names declared inside namespaces. Specifically, to access
  such names we must continue using the existing mechanisms, such as
  qualification or using declaration/directive. For example:</p>

  <pre>import hello.core;        // Exports hello::say().

say ();                   // Error.
hello::say ();            // Ok.

using namespace hello;
say ();                   // Ok.</pre>

  <p>Note also that from the consumer's perspective a module does not provide
  any symbols, only C++ entity names. If we use names from a module, then we
  may have to satisfy the corresponding symbols using the usual mechanisms:
  link an object file or a library that provides them. In this respect,
  modules are similar to headers and as with headers, module's use is not
  limited to libraries; they make perfect sense when structuring programs.
  Furthermore, a library may also have private or implementation modules that
  are not meant to be imported by the library's consumers.</p>

  <p>The producer perspective on modules is predictably more complex. In
  pre-modules C++ we only had one kind of translation unit (or source file).
  With modules there are three kinds: <i>module interface unit</i>, <i>module
  implementation unit</i>, and the original kind which we will call a
  <i>non-module translation unit</i>.</p>

  <div class="note">
  <p>There are two additional modular translation units: module interface
  partition and module implementation partition. While partitions are
  supported, they are not covered in this introduction. A link to a complete
  example that uses both types of partitions will be given in the next
  section.</p>
  </div>

  <p>From the producer's perspective, a module is a collection of module
  translation units: one interface unit and zero or more implementation units.
  A simple module may consist of just the interface unit that includes
  implementations of all its functions (not necessarily inline). A more
  complex module may span multiple implementation units.</p>

  <p>A translation unit is a module interface unit if it contains an
  <i>exporting module declaration</i>:</p>

  <pre>export module hello;</pre>

  <p>A translation unit is a module implementation unit if it contains a
  <i>non-exporting module declaration</i>:</p>

  <pre>module hello;</pre>

  <p>While module interface units may use the same file extension as normal
  source files, we recommend that a different extension be used to distinguish
  them as such, similar to header files. While the compiler vendors suggest
  various (and predictably different) extensions, our recommendation is
  <code>.mxx</code> for the <code>.hxx/.cxx</code> source file naming and
  <code>.mpp</code> for <code>.hpp/.cpp</code>. And if you are using some
  other naming scheme, then perhaps now is a good opportunity to switch to one
  of the above. Continuing using the source file extension for module
  implementation units appears reasonable and that's what we recommend.</p>

  <p>A modular translation unit (that is, either module interface or
  implementation) that does not start with one of the above module
  declarations must then start with the module introducer:</p>

  <pre>module;

...

export module hello;</pre>

  <p>The fragment from the module introducer and until the module declaration
  is called the <i>global module fragment</i>. Any name declared in the global
  module fragment belongs to the <i>global module</i>, an implied module
  containing "old" or non-modular declarations that don't belong to any named
  module.</p>

  <p>A module declaration (exporting or non-exporting) starts a <i>module
  purview</i> that extends until the end of the module translation unit. Any
  name declared in a module's purview <i>belongs</i> to the said module. For
  example:</p>

  <pre>module;                               // Start of global module fragment.

#include &lt;cassert>                    // Not in purview.

export module hello;                  // Start of purview.

import std;                           // In purview.

void say_hello (const std::string&amp;);  // In purview.</pre>

  <p>A name that belongs to a module is <i>invisible</i> to the module's
  consumers unless it is <i>exported</i>. A name can be declared exported only
  in a module interface unit, only in the module's purview, and there are
  several syntactic ways to accomplish this. We can start the declaration with
  the <code>export</code> specifier, for example:</p>

  <pre>export module hello;

export enum class volume {quiet, normal, loud};

export void say_hello (const char*, volume);</pre>

  <p>Alternatively, we can enclose one or more declarations into an
  <i>exported group</i>, for example:</p>

  <pre>export module hello;

export
{
  enum class volume {quiet, normal, loud};

  void say_hello (const char*, volume);
}</pre>

  <p>Finally, if a namespace definition is declared exported, then every name
  in its body is exported, for example:</p>

  <pre>export module hello;

export namespace hello
{
  enum class volume {quiet, normal, loud};

  void say_hello (const char*, volume);
}

namespace hello
{
  void impl (const char*, volume); // Not exported.
}</pre>

  <p>Up until now we've only been talking about names belonging to a module.
  What about the corresponding symbols? All the major C++ compilers have
  chosen to implement the so-called strong ownership model, where for both
  exported and non-exported names, the corresponding symbols are decorated
  with the module name.  As a result, they cannot clash with symbols for
  identical names from other named modules or the global module.</p>

  <p>What about the preprocessor? Modules do not export preprocessor macros,
  only C++ names. A macro defined in the module interface unit cannot affect
  the module's consumers. And macros defined by the module's consumers cannot
  affect the module interface they are importing. In other words, module
  producers and consumers are isolated from each other where the preprocessor
  is concerned. For example, consider this module interface:</p>

  <pre>export module hello;

#ifndef SMALL
#define HELLO
export void say_hello (const char*);
#endif</pre>

  <p>And its consumer:</p>

  <pre>// module consumer
//
#define SMALL       // No effect.
import hello;

#ifdef HELLO        // Not defined.
...
#endif</pre>

  <p>This is not to say that the preprocessor cannot be used by either the
  module interface or its consumer, it just that macros don't "leak" through
  the module interface. One practical consequence of this model is the
  insignificance of the importation order.</p>

  <p>If a module imports another module in its purview, the imported module's
  names are not made automatically visible to the consumers of the importing
  module. This is unlike headers and can be surprising. Consider this module
  interface as an example:</p>

  <pre>export module hello;

import std;

export std::string formal_hello (const std::string&amp;);</pre>

  <p>And its consumer:</p>

  <pre>import hello;

int
main ()
{
  std::string s (format_hello ("World"));
}</pre>

  <p>This example will result in a compile error and the diagnostics may
  confusingly indicate that there is no member <code>string</code> in
  namespace <code>std</code>. But with the understanding of the difference
  between <code>import</code> and <code>#include</code> the reason should be
  clear: while the module interface "sees" <code>std::string</code> (because
  it imported its module), we (the consumer) do not (since we did not). So the
  fix is to explicitly import <code>std</code>:</p>

  <pre>import std;
import hello;

int
main ()
{
  std::string s (format_hello ("World"));
}</pre>

  <p>A module, however, can choose to re-export a module it imports. In this
  case, all the names from the imported module will also be visible to the
  importing module's consumers. For example, with this change to the module
  interface the first version of our consumer will compile without errors
  (note that whether this is a good design choice is debatable, as discussed
  below):</p>

  <pre>export module hello;

export import std;

export std::string formal_hello (const std::string&amp;);</pre>

  <p>One way to think of a re-export is <i>as if</i> an import of a module
  also "injects" all the imports the said module re-exports, recursively.
  That's essentially how most compilers implement it.</p>

  <p>Module re-export is the mechanism for assembling bigger modules out of
  submodules. As an example, let's say we had the <code>hello.core</code>,
  <code>hello.basic</code>, and <code>hello.extra</code> modules. To make life
  easier for users that want to import all of them we can create the
  <code>hello</code> module that re-exports the three:</p>

  <pre>export module hello;

export
{
  import hello.core;
  import hello.basic;
  import hello.extra;
}</pre>

  <p>Besides starting a module purview, a non-exporting module declaration in
  the implementation unit makes (non-internal linkage) names declared or made
  visible (via import) in the module purview of an interface unit also visible
  in the module purview of the implementation unit. In this sense a
  non-exporting module declaration acts as a special <code>import</code>. The
  following example illustrates this point:</p>

  <pre>module;

import hello.impl;          // Not visible (exports impl()).

#include &lt;string.h>         // Not visible (declares strlen()).

export module hello.extra;  // Start of module purview (interface).

import hello.core;          // Visible (exports core()).

void extra ();              // Visible.

static void extra2 ();      // Not visible (internal linkage).</pre>

  <p>And this is the implementation unit:</p>

  <pre>module hello.extra;         // Start of module purview (implementation).

void
f ()
{
  impl ();      // Error.
  strlen ("");  // Error.
  core ();      // Ok.
  extra ();     // Ok.
  extra2 ();    // Error.
}</pre>

  <p>In particular, this means that while the relative order of imports is not
  significant, the placement of imports in the module interface unit relative
  to the module declaration can be.</p>

  <p>The final perspective that we consider is that of the build system. From
  its point of view the central piece of the module infrastructure is the
  <i>binary module interface</i> or BMI: a binary file that is produced by
  compiling the module interface unit and that is required when compiling any
  translation unit that imports this module as well as the module's
  implementation units.</p>

  <p>Then, in a nutshell, the main functionality of a build system when it
  comes to modules support is figuring out the order in which all the
  translation units should be compiled and making sure that every compilation
  process is able to find the binary module interfaces it needs.</p>

  <p>Predictably, the details are more complex. Compiling a module interface
  unit produces two outputs: the binary module interface and the object file.
  The latter contains object code for non-inline functions, global variables,
  etc., that the interface unit may define. This object file has to be linked
  when producing any binary (program or library) that uses this module.</p>

  <p>Also, all the compilers currently implement module re-export as a shallow
  reference to the re-exported module name which means that their binary
  interfaces must be discoverable as well, recursively. In fact, currently,
  all the imports are handled like this, though a different implementation is
  at least plausible, if unlikely.</p>

  <p>While the details vary between compilers, the contents of the binary
  module interface can range from a stream of preprocessed tokens to something
  fairly close to object code. As a result, binary interfaces can be sensitive
  to the compiler options and if the options used to produce the binary
  interface (for example, when building a library) are sufficiently different
  compared to the ones used when compiling the module consumers, the binary
  interface may be unusable. So while a build system should strive to reuse
  existing binary interfaces, it should also be prepared to compile its own
  versions "on the side".</p>

  <p>This also suggests that binary module interfaces are not a distribution
  mechanism and should probably not be installed. Instead, we should install
  and distribute module interface sources and build systems should be prepared
  to compile them, again, on the side.</p>

  <h3 id="cxx-modules-build">16.3.2 Building Modules</h3>

  <p>Compiler support for C++ modules is still experimental, incomplete, and
  often buggy. Also, in <code>build2</code>, the presence of modules changes
  the C++ compilation model in ways that would introduce unnecessary overheads
  for headers-only code. As a result, a project must explicitly enable modules
  using the <code>cxx.features.modules</code> boolean variable. This is what
  the relevant <code>root.build</code> fragment could look like for a
  modularized project:</p>

  <pre>cxx.std = latest
cxx.features.modules = true

using cxx

mxx{*}: extension = mxx
cxx{*}: extension = cxx</pre>

  <div class="note">
  <p>Note that you must explicitly enable modules in your project even if you
  are only importing other modules, including standard library modules
  (<code>std</code> or <code>std.compat</code>).</p>
  </div>

  <p>To support C++ modules the <code>cxx</code> build system module defines
  several additional target types. The <code>mxx{}</code> target is a module
  interface unit. As you can see from the above <code>root.build</code>
  fragment, in this project we are using the <code>.mxx</code> extension for
  our module interface files. While you can use the same extension as for
  <code>cxx{}</code> (source files), this is not recommended since some
  functionality, such as wildcard patterns, will become unusable.</p>

  <p>The <code>bmi{}</code> group and its <code>bmie{}</code>,
  <code>bmia{}</code>, and <code>bmis{}</code> members are used to represent
  binary module interfaces targets. We normally do not need to mention them
  explicitly in our <code>buildfiles</code> except, perhaps, to specify
  additional, module interface-specific compile options.</p>

  <p>To build a modularized executable or library we simply list the module
  interfaces as its prerequisites, just as we do for source files. As an
  example, let's build the <code>hello</code> program that we have started in
  the introduction (you can find the complete project in the <a
  href="https://github.com/build2/cxx20-modules-examples/tree/named-only-import-std"><code>cxx20-modules-examples</code></a>
  repository under <code>hello-module</code>). Specifically, we assume our
  project contains the following files:</p>

  <pre>// file: hello.mxx (module interface)

export module hello;

import std;

export namespace hello
{
  void say_hello (const std::string_view&amp; name);
}</pre>

  <pre>// file: hello.cxx (module implementation)

module hello;

namespace hello
{
  void say_hello (const std::string_view&amp; n)
  {
    std::cout &lt;&lt; "Hello, " &lt;&lt; n &lt;&lt; '!' &lt;&lt; std::endl;
  }
}</pre>

  <pre>// file: main.cxx

import hello;

int
main ()
{
  hello::say_hello ("World");
}</pre>

  <p>To build a <code>hello</code> executable from these files we can write
  the following <code>buildfile</code>:</p>

  <pre>exe{hello}: cxx{main} {mxx cxx}{hello}</pre>

  <p>Or, if you prefer to use wildcard patterns:</p>

  <pre>exe{hello}: {mxx cxx}{*}</pre>

  <div class="note">
  <p>Module partitions, both interface and implementation, are compiled to
  BMIs and as a result must be listed as <code>mxx{}</code> prerequisites. See
  <code>hello-partition</code> in the <a
  href="https://github.com/build2/cxx20-modules-examples/tree/named-only-import-std"><code>cxx20-modules-examples</code></a>
  repository for a complete example.</p>
  </div>

  <p>Alternatively, we can place the module into a library and then link the
  library to the executable (see <code>hello-library-module</code> in the <a
  href="https://github.com/build2/cxx20-modules-examples/tree/named-only-import-std"><code>cxx20-modules-examples</code></a>
  repository):</p>

  <pre>exe{hello}: cxx{main} lib{hello}
lib{hello}: {mxx cxx}{hello}</pre>

  <p>Note that a library consisting of only module interface units is by
  default always binful (see <a href="#intro-lib">Library Exportation and
  Versioning</a> for background) since compiling a module interface always
  results in an object file, even if the module interface does not contain any
  non-inline/template functions or global variables. However, you can
  explicitly request for such a library to be treated as binless:</p>

  <pre>lib{hello}: mxx{hello}
{
  bin.binless = true
}</pre>

  <div class="note">
  <p>Note that if such a binless library has non-inline/template functions or
  global variables, then whether it can used in all situations without causing
  duplicate symbols is platform-dependent.</p>
  </div>

  <p>As you might have surmised from this example, the modules support in
  <code>build2</code> automatically resolves imports to module interface units
  that are specified either as direct prerequisites or as prerequisites of
  library prerequisites.</p>

  <p>To perform this resolution without a significant overhead, the
  implementation delays the extraction of the actual module name from module
  interface units (since not all available module interfaces are necessarily
  imported by all the translation units). Instead, the implementation tries to
  guess which interface unit implements each module being imported based on
  the interface file path. Or, more precisely, a two-step resolution process
  is performed: first a best match between the desired module name and the
  file path is sought and then the actual module name is extracted and the
  correctness of the initial guess is verified.</p>

  <p>The practical implication of this implementation detail is that our
  module interface files must embed a portion of a module name, or, more
  precisely, a sufficient amount of "module name tail" to unambiguously
  resolve all the modules used in a project. Note that this guesswork is only
  performed for direct module interface prerequisites; for those that come
  from libraries the module names are known and are therefore matched exactly.
  And the guesses are always verified before the actual compilation, so
  misguesses cannot go unnoticed.</p>

  <p>As an example, let's assume our <code>hello</code> project had two
  modules: <code>hello.core</code> and <code>hello.extra</code>. While we
  could call our interface files <code>hello.core.mxx</code> and
  <code>hello.extra.mxx</code>, respectively, this doesn't look particularly
  good and may be contrary to the file naming scheme used in our project. To
  resolve this issue the match of module names to file names is made "fuzzy":
  it is case-insensitive, it treats all separators (dots, dashes, underscores,
  etc) as equal, and it treats a case change as an imaginary separator. As a
  result, the following naming schemes will all match the
  <code>hello.core</code> module name:</p>

  <pre>hello-core.mxx
hello_core.mxx
HelloCore.mxx
hello/core.mxx</pre>

  <p>We also don't have to embed the full module name. In our case, for
  example, it would be most natural to call the files <code>core.mxx</code>
  and <code>extra.mxx</code> since they are already in the project directory
  called <code>hello/</code>. This will work since our module names can still
  be guessed correctly and unambiguously.</p>

  <p>If a guess turns out to be incorrect, the implementation issues
  diagnostics and exits with an error before attempting to build anything. To
  resolve this situation we can either adjust the interface file names or we
  can specify the module name explicitly with the <code>cxx.module_name</code>
  variable. The latter approach can be used with interface file names that
  have nothing in common with module names, for example:</p>

  <pre>mxx{foobar}@./: cxx.module_name = hello</pre>

  <p>Note also that the standard library modules (<code>std</code> and
  <code>std.compat</code>) are treated specially and are resolved in a
  compiler-specific manner.</p>

  <p>When C++ modules are enabled and available, the build system makes sure
  the <code>__cpp_modules</code> feature test macro is defined. However, if
  the compiler version being used does not claim complete modules support, its
  value may not be <code>201907</code>.</p>

  <h3 id="cxx-modules-symexport">16.3.3 Module Symbols Exporting</h3>

  <p>When building a shared library, some platforms (notably Windows) require
  that we explicitly export symbols that must be accessible to the library
  consumers. If you don't need to support such platforms, you can thank your
  lucky stars and skip this section.</p>

  <p>When using headers, the traditional way of achieving this is via an
  "export macro" that is used to mark exported APIs, for example:</p>

  <pre>LIBHELLO_EXPORT void say_hello (const string&amp;);</pre>

  <p>This macro is then appropriately defined (often in a separate "export
  header") to export symbols when building the shared library and to import
  them when building the library's consumers (and to nothing when either
  building or consuming the static library).</p>

  <p>The introduction of modules changes this in a number of ways, at least as
  implemented by MSVC and Clang. While we still have to explicitly mark
  exported symbols in our module interface unit, there is no need (and, in
  fact, no way) to do the same when said module is imported. Instead, the
  compiler automatically treats all such explicitly exported symbols (note:
  symbols, not names) as imported.</p>

  <div class="note">
  <p>While the automatic importing may look like the same mechanism as what's
  used to support <a href="#cc-auto-symexport">Automatic DLL Symbol
  Exporting</a>, it appears not to be since it also works for global
  variables, not only functions. However, reportedly, it does appear to incur
  the same additional overhead as auto-importing, at least for functions.</p>
  </div>

  <p>One notable aspect of this new model is the locality of the export macro:
  it is only defined when compiling the module interface unit and is not
  visible to the consumers of the module. This is unlike headers where the
  macro has to have a unique per-library name (that <code>LIBHELLO_</code>
  prefix) because a header from one library can be included while building
  another library.</p>

  <p>We can continue using the same export macro and header with modules and,
  in fact, that's the recommended approach if maintaining the dual,
  header/module arrangement for backwards compatibility. However, for
  modules-only codebases, we have an opportunity to improve the situation in
  two ways: we can use a single, keyword-like macro instead of a
  library-specific one and we can make the build system manage it for us thus
  getting rid of the export header.</p>

  <p>To enable this functionality in <code>build2</code> we set the
  <code>cxx.features.symexport</code> boolean variable to <code>true</code>
  before loading the <code>cxx</code> module. For example:</p>

  <pre>cxx.std = latest
cxx.features.modules = true
cxx.features.symexport = true

using cxx

...</pre>

  <p>Once enabled, <code>build2</code> automatically defines the
  <code>__symexport</code> macro to the appropriate value depending on the
  platform and the type of library being built. As library authors, all we
  have to do is use it in appropriate places in our module interface units,
  for example:</p>

  <pre>export module hello;

import std;

export __symexport void say_hello (const std::string&amp;);</pre>

  <div class="note">
  <p>You may be wondering why can't a module export automatically mean a
  symbol export? While you will normally want to export symbols of all your
  module-exported names, you may also need to do so for some
  non-module-exported ones. For example:</p>

  <pre>export module foo;

__symexport void f_impl ();

export __symexport inline void f ()
{
  f_impl ();
}</pre>

  <p>Furthermore, symbol exporting is a murky area with many limitations and
  pitfalls (such as auto-exporting of base classes). As a result, it would not
  be unreasonable to expect such an automatic module exporting to only further
  muddy the matter.</p>
  </div>

  <h3 id="cxx-modules-install">16.3.4 Modules Installation</h3>

  <p>As discussed in the introduction, binary module interfaces are not a
  distribution mechanism and installing module interface sources appears to be
  the preferred approach.</p>

  <p>Module interface units are by default installed in the same location as
  headers (for example, <code>/usr/include</code>). However, instead of
  relying on a header-like search mechanism (<code>-I</code> paths, etc.), an
  explicit list of exported modules is provided for each library in its
  <code>.pc</code> (<code>pkg-config</code>) file.</p>

  <p>Specifically, the library's <code>.pc</code> file contains the
  <code>cxx.modules</code> variable that lists all the exported C++ modules in
  the <code>&lt;name>=&lt;path></code> form with <code>&lt;name></code> being
  the module's C++ name and <code>&lt;path></code> &#8211; the module
  interface file's absolute path. For example:</p>

  <pre>Name: libhello
Version: 1.0.0
Cflags:
Libs: -L/usr/lib -lhello

cxx.modules = hello.core=/usr/include/hello/core.mxx hello.extra=/usr/include/hello/extra.mxx</pre>

  <div class="note">
  <p>The <code>:</code> character in a module partition name is encoded as
  <code>..</code>. For example, for <code>hello:core</code> we would have:</p>

  <pre>cxx.modules = hello..core=/usr/...</pre>
  </div>

  <p>Additional module properties are specified with variables in the
  <code>cxx.module_&lt;property>.&lt;name></code> form, for example:</p>

  <pre>cxx.module_symexport.hello.core = true
cxx.module_preprocessed.hello.core = all</pre>

  <p>Currently, two properties are defined. The <code>symexport</code>
  property with the boolean value signals whether the module uses the
  <code>__symexport</code> support discussed above.</p>

  <p>The <code>preprocessed</code> property indicates the degree of
  preprocessing the module unit requires and is used to optimize module
  compilation. Valid values are <code>none</code> (not preprocessed),
  <code>includes</code> (no <code>#include</code> directives in the source),
  <code>modules</code> (as above plus no module declarations depend on the
  preprocessor, for example, <code>#ifdef</code>, etc.), and <code>all</code>
  (the source is fully preprocessed). Note that for <code>all</code> the
  source may still contain comments and line continuations.</p>

  <h3 id="cxx-modules-guidelines">16.3.5 Modules Design Guidelines</h3>

  <p>Modules are a physical design mechanism for structuring and organizing
  our code. Their explicit exportation semantics combined with the way they
  are built make many aspects of creating and consuming modules significantly
  different compared to headers. This section provides basic guidelines for
  designing modules. We start with the overall considerations such as module
  granularity and partitioning into translation units then continue with the
  structure of typical module interface and implementation units. The
  following section discusses practical approaches to modularizing existing
  code.</p>

  <p>Unlike headers, the cost of importing modules should be negligible. As a
  result, it may be tempting to create "mega-modules", for example, one per
  library. After all, this is how the standard library is modularized with its
  <code>std</code> and <code>std.compat</code> modules.</p>

  <p>There is, however, a significant drawback to this choice: every time we
  make a change, all consumers of such a mega-module will have to be
  recompiled, whether the change affects them or not. And the bigger the
  module the higher the chance that any given change does not (semantically)
  affect a large portion of the module's consumers. Note also that this is not
  an issue for the standard library modules since they are not expected to
  change often.</p>

  <p>Another, more subtle, issue with mega-modules (which does affect the
  standard library) is the inability to re-export only specific interfaces, as
  will be discussed below.</p>

  <p>The other extreme in choosing module granularity is a large number of
  "mini-modules". Their main drawback is the tediousness of importation by the
  consumers.</p>

  <p>The sensible approach is then to create modules of conceptually-related
  and commonly-used entities possibly complemented with aggregate modules for
  ease of importation. This also happens to be generally good design.</p>

  <p>As an example, let's consider a JSON library that provides support for
  both parsing and serialization. Since it is common for applications to only
  use one of the functionalities, it makes sense to provide the
  <code>json.parser</code> and <code>json.serializer</code> modules. Depending
  on the representation of JSON we use in our library, it will most likely
  have some shared types so it probably makes sense to have the
  <code>json.types</code> module that is re-exported by the parser and
  serializer modules. While it is not too tedious to import both
  <code>json.parser</code> and <code>json.serializer</code> if both a needed,
  for convenience we could also provide the <code>json</code> module that
  re-exports the two. Something along these lines:</p>

  <pre>// types.mxx

export module json.types;

export class json
{
 ...
};</pre>

  <pre>// parser.mxx

export module json.parser;

export import json.types;

export json parse (...);</pre>

  <pre>// serializer.mxx

export module json.serializer;

export import json.types;

export ... serialize (const json&amp;);</pre>

  <pre>// json.mxx

export module json;

export import json.types;
export import json.parser;
export import json.serializer;</pre>

  <p>Once we are past selecting an appropriate granularity for our modules,
  the next question is how to partition them into translation units. A module
  can consist of just the interface unit and, as discussed above, such a unit
  can contain anything an implementation unit can, including non-inline
  function definitions. Some may then view this as an opportunity to get rid
  of the header/source separation and have everything in a single file.</p>

  <p>There are a number of drawbacks with this approach: Every time we change
  anything in the module interface unit, all its consumers have to be
  recompiled. If we keep everything in a single file, then every time we
  change the implementation we trigger recompilations that would have been
  avoided had the implementation been factored out into a separate unit. Note
  that a build system in cooperation with the compiler could theoretically
  avoid such unnecessary recompilations in certain cases: if the compiler
  produces identical binary interface files when the module interface is
  unchanged, then the build system could detect this and skip recompiling the
  module's consumers.</p>

  <p>A related issue with single-file modules is the reduction in the build
  parallelization opportunities. If the implementation is part of the
  interface unit, then the build system cannot start compiling the module's
  consumers until both the interface and the implementation are compiled. On
  the other hand, had the implementation been split into a separate file, the
  build system could start compiling the module's consumers (as well as the
  implementation unit) as soon as the module interface is compiled.</p>

  <p>Another issues with combining the interface with the implementation is
  the readability of the interface which could be significantly reduced if
  littered with implementation details. We could keep the interface separate
  by moving the implementation to the bottom of the interface file but then we
  might as well move it into a separate file and avoid the unnecessary
  recompilations or parallelization issues.</p>

  <p>The sensible guideline is then to have a separate module implementation
  unit except perhaps for modules with a simple implementation that is mostly
  inline/template. Note that more complex modules may have several
  implementation units, however, based on our granularity guideline, those
  should be rare.</p>

  <p>Once we start writing our first real module the immediate question that
  normally comes up is where to put <code>#include</code> directives and
  <code>import</code> declarations and in what order. To recap, a module unit,
  both interface and implementation, is split into two parts: before the
  module declaration, called the global module fragment, which obeys the usual
  or "old" translation unit rules and after the module declaration which is
  the module purview. Inside the module purview all declarations have their
  symbols invisible to any other module (including the global module). With
  this understanding, consider the following module interface:</p>

  <pre>export module hello;

#include &lt;string></pre>

  <p>Do you see the problem? We have included <code>&lt;string></code> in the
  module purview which means all its names (as well as all the names in any
  headers it might include, recursively) are now declared as having the
  <code>hello</code> module linkage. The result of doing this can range from
  silent code blot to strange-looking unresolved symbols.</p>

  <p>The guideline this leads to should be clear: including a header in the
  module purview is almost always a bad idea. There are, however, a few types
  of headers that may make sense to include in the module purview. The first
  are headers that only define preprocessor macros, for example, configuration
  or export headers. There are also cases where we do want the included
  declarations to end up in the module purview. The most common example is
  inline/template function implementations that have been factored out into
  separate files for code organization reasons. As an example, consider the
  following module interface that uses an export header (which presumably sets
  up symbols exporting macros) as well as an inline file:</p>

  <pre>module;

#include &lt;string>

export module hello;

#include &lt;libhello/export.hxx>

export namespace hello
{
  ...
}

#include &lt;libhello/hello.ixx></pre>

  <p>A note on inline/template files: in header-based projects we could
  include additional headers in those files, for example, if the included
  declarations are only needed in the implementation. For the reasons just
  discussed, this does not work with modules and we have to move all the
  includes into the interface file, into the global module fragment. On the
  other hand, with modules, it is safe to use namespace-level using-directives
  (for example, <code>using namespace std;</code>) in inline/template files
  (and, with care, even in the interface file).</p>

  <p>What about imports, where should we import other modules? Again, to
  recap, unlike a header inclusion, an <code>import</code> declaration only
  makes exported names visible without redeclaring them. As result, in module
  implementation units, it doesn't really matter where we place imports, in
  the module purview or the global module fragment. There are, however, two
  differences when it comes to module interface units: only imports in the
  purview are visible to implementation units and we can only re-export an
  imported module from the purview.</p>

  <p>The guideline is then for interface units to import in the module purview
  unless there is a good reason not to make the import visible to the
  implementation units. And for implementation units to always import in the
  purview for simplicity. For example:</p>

  <pre>module;

#include &lt;cassert>

export module hello;

import std;

#include &lt;libhello/export.hxx>

export namespace hello
{
  ...
}

#include &lt;libhello/hello.ixx></pre>

  <p>By putting all these guidelines together we can then create a module
  interface unit template:</p>

  <pre>// Module interface unit.

module;                    // Start of global module fragment.

&lt;header includes>

export module &lt;name>;      // Start of module purview.

&lt;module imports>

&lt;special header includes>  // Configuration, export, etc.

&lt;module interface>

&lt;inline/template includes></pre>

  <p>As well as the module implementation unit template:</p>

  <pre>// Module implementation unit.

module;                    // Start of global module fragment.

&lt;header includes>

module &lt;name>;             // Start of module purview.

&lt;extra module imports>     // Only additional to interface.

&lt;module implementation></pre>

  <p>Let's now discuss module naming. Module names are in a separate "name
  plane" and do not collide with namespace, type, or function names. Also, as
  mentioned earlier, the standard does not assign a hierarchical meaning to
  module names though it is customary to assume module <code>hello.core</code>
  is a submodule of <code>hello</code> and, unless stated explicitly
  otherwise, importing the latter also imports the former.</p>

  <p>It is important to choose good names for public modules (that is, modules
  packaged into libraries and used by a wide range of consumers) since
  changing them later can be costly. We have more leeway with naming private
  modules (that is, the ones used by programs or internal to libraries) though
  it's worth coming up with a consistent naming scheme here as well.</p>

  <p>The general guideline is to start names of public modules with the
  library's namespace name followed by a name describing the module's
  functionality. In particular, if a module is dedicated to a single class
  (or, more generally, has a single primary entity), then it makes sense to
  use that name as the module name's last component.</p>

  <p>As a concrete example, consider <code>libbutl</code> (the
  <code>build2</code> utility library): All its components are in the
  <code>butl</code> namespace so all its module names start with
  <code>butl.</code> One of its components is the <code>small_vector</code>
  class template which resides in its own module called
  <code>butl.small_vector</code>. Another component is a collection of string
  parsing utilities that are grouped into the <code>butl::string_parser</code>
  namespace with the corresponding module called
  <code>butl.string_parser</code>.</p>

  <p>When is it a good idea to re-export a module? The two straightforward
  cases are when we are building an aggregate module out of submodules, for
  example, <code>json</code> out of <code>json.parser</code> and
  <code>json.serializer</code>, or when one module extends or supersedes
  another, for example, as <code>json.parser</code> extends
  <code>json.types</code>. It is also clear that there is no need to re-export
  a module that we only use in the implementation. The case when we use a
  module in our interface is, however, a lot less clear cut.</p>

  <p>But before considering the last case in more detail, let's understand the
  issue with re-export. In other words, why not simply re-export any module we
  import in our interface? In essence, re-export implicitly injects another
  module import anywhere our module is imported. If we re-export
  <code>std</code> then consumers of our module will also automatically "see"
  all the names exported by <code>std</code>. They can then start using names
  from <code>std</code> without explicitly importing <code>std</code> and
  everything will compile until one day they no longer need to import our
  module or we no longer need to import <code>std</code>. In a sense,
  re-export becomes part of our interface and it is generally good design to
  keep interfaces minimal.</p>

  <p>And so, at the outset, the guideline is then to only re-export the
  minimum necessary.</p>

  <p>Let's now discuss a few concrete examples to get a sense of when
  re-export might or might not be appropriate. Unfortunately, there does not
  seem to be a hard and fast rule and instead one has to rely on their good
  sense of design.</p>

  <p>To start, let's consider a simple module that uses
  <code>std::string</code> in its interface:</p>

  <pre>export module hello;

import std;

export namespace hello
{
  std::string format_hello (const std::string&amp;);
}</pre>

  <p>Should we re-export <code>std</code> in this case? Most likely not. If
  consumers of our module want to refer to <code>std::string</code>, then it
  is natural to expect them to explicitly import the necessary module. In a
  sense, this is analogous to scoping: nobody expects to be able to use just
  <code>string</code> (without <code>std::</code>) because of <code>using
  namespace hello;</code>.</p>

  <p>So it seems that a mere usage of a name in an interface does not
  generally warrant a re-export. The fact that a consumer may not even use
  this part of our interface further supports this conclusion.</p>

  <p>Let's now consider a more interesting case (inspired by real events):</p>

  <pre>export module small_vector;

import std;

template &lt;typename T, std::size_t N>
export class small_vector: public std::vector&lt;T, ...>
{
  ...
};</pre>

  <p>Here we have the <code>small_vector</code> container implemented in terms
  of <code>std::vector</code> by providing a custom allocator and with most of
  the functions derived as is. Consider now this innocent-looking consumer
  code:</p>

  <pre>import small_vector;

small_vector&lt;int, 1> a, b;

if (a == b) // Error.
  ...</pre>

  <p>We don't reference <code>std::vector</code> directly so presumably we
  shouldn't need to import its module. However, the comparison won't compile:
  our <code>small_vector</code> implementation re-uses the comparison
  operators provided by <code>std::vector</code> (via implicit to-base
  conversion) but they aren't visible.</p>

  <p>There is a palpable difference between the two cases: the first merely
  uses <code>std</code> interface while the second is <i>based on</i> and, in
  a sense, <i>extends</i> it which feels like a stronger relationship.
  Re-exporting <code>std</code> (or, better yet, <code>std.vector</code>, if
  it were available) seems less unreasonable.</p>

  <p>Note also that there is no re-export of headers nor header inclusion
  visibility in the implementation units. Specifically, in the previous
  example, if the standard library is not modularized and we have to use it
  via headers, then the consumers of our <code>small_vector</code> will always
  have to explicitly include <code>&lt;vector></code>. This suggest that
  modularizing a codebase that still consumes substantial components (like the
  standard library) via headers can incur some development overhead compared
  to the old, headers-only approach.</p>

  <h3 id="cxx-modules-existing">16.3.6 Modularizing Existing Code</h3>

  <p>The aim of this section is to provide practical guidelines to
  modularizing existing codebases.</p>

  <p>Predictably, a well modularized (in the general sense) set of headers
  makes conversion to C++ modules easier. Inclusion cycles will be
  particularly hard to deal with (C++ modules do not allow circular interface
  dependencies). Having a one-to-one header to module mapping will simplify
  this task. As a result, it may make sense to spend some time cleaning and
  re-organizing your headers prior to attempting modularization.</p>

  <p>The recommended strategy for modularizing our own components is to
  identify and modularize inter-dependent sets of headers one at a time
  starting from the lower-level components. This way any newly modularized set
  will only depend on the already modularized ones. After converting each set
  we can switch its consumers to using imports keeping our entire project
  buildable and usable.</p>

  <p>While ideally we would want to be able to modularize just a single
  component at a time, this does not seem to work in practice because we will
  have to continue consuming some of the components as headers. Since such
  headers can only be imported out of the module purview, it becomes hard to
  reason (both for us and often the compiler) what is imported/included and
  where. For example, it's not uncommon to end up importing the module in its
  implementation unit which is not something that all the compilers can handle
  gracefully.</p>

  <p>If our module needs to "export" macros then the recommended approach is
  to simply provide an additional header that the consumer includes. While it
  might be tempting to also wrap the module import into this header, some may
  prefer to explicitly import the module and include the header, especially if
  the macros may not be needed by all consumers. This way we can also keep the
  header macro-only which means it can be included freely, in or out of module
  purviews.</p>

  <h2 id="cxx-objcxx">16.4 Objective-C++ Compilation</h2>

  <p>The <code>cxx</code> module provides the <code>cxx.objcxx</code>
  submodule which can be loaded in order to register the <code>mm{}</code>
  target type and enable Objective-C++ compilation in the <code>C++</code>
  compile rule. Note that <code>cxx.objcxx</code> must be loaded after the
  <code>cxx</code> module and while the <code>mm{}</code> target type is
  registered unconditionally, compilation is only enabled if the C++ compiler
  supports Objective-C++ for the target platform. Typical usage:</p>

  <pre># root.build
#
using cxx
using cxx.objcxx</pre>

  <pre># buildfile
#
lib{hello}: {hxx cxx}{*}
lib{hello}: mm{*}: include = ($cxx.target.class  == 'macos')</pre>

  <p>Note also that while there is support for linking Objective-C++
  executables and libraries, this is done using the C++ compiler driver and no
  attempt is made to automatically link any necessary Objective-C runtime
  library (such as <code>-lobjc</code>).</p>

  <h2 id="cxx-predefs">16.5 C++ Compiler Predefined Macro Extraction</h2>

  <p>The <code>cxx</code> module provides the <code>cxx.predefs</code>
  submodule which can be loaded in order to register a rule that generates a
  C++ header with predefined compiler macros. Note that the
  <code>cxx.predefs</code> module must be loaded after the <code>cxx</code>
  module and the rule will only match with an explicit rule hint. Typical
  usage:</p>

  <pre># root.build
#
using cxx
using cxx.predefs</pre>

  <pre># buildfile
#
[rule_hint=cxx.predefs] hxx{predefs}:</pre>

  <p>Note also that the MSVC compiler only supports the predefined macro
  extraction starting from Visual Studio 2019 (16.0; <code>cl.exe</code>
  version 19.20). If support for earlier versions is required, then you will
  need to provide a fallback implementation appropriate for your project. For
  example:</p>

  <pre>[rule_hint=cxx.predefs] hxx{predefs}:
% update
if ($cxx.id == 'msvc' &amp;&amp; \
    ($cxx.version.major &lt; 19 || \
     ($cxx.version.major == 19 &amp;&amp; $cxx.version.minor &lt; 20)))
{{
  diag c++-predefs $>

  cat &lt;&lt;EOF >$path($>)
  #define _WIN32
  #define __cplusplus 201402L
  EOF
}}</pre>

  <h1 id="module-in">17 <code>in</code> Module</h1>

  <p>The <code>in</code> build system module provides support for
  <code>.in</code> (input) file preprocessing. Specifically, the
  <code>.in</code> file can contain a number of <i>substitutions</i> &#8211;
  build system variable names enclosed with the substitution symbol
  (<code>$</code> by default) &#8211; which are replaced with the
  corresponding variable values to produce the output file. For example:</p>

  <pre># build/root.build

using in</pre>

  <pre>// config.hxx.in

#define TARGET "$cxx.target$"</pre>

  <pre># buildfile

hxx{config}: in{config}</pre>

  <p>The <code>in</code> module defines the <code>in{}</code> target type and
  implements the <code>in</code> build system rule.</p>

  <p>While we can specify the <code>.in</code> extension explicitly, it is not
  necessary because the <code>in{}</code> target type implements
  <i>target-dependent search</i> by taking into account the target it is a
  prerequisite of. In other words, the following dependency declarations
  produce the same result:</p>

  <pre>hxx{config}:     in{config}
hxx{config.hxx}: in{config}
hxx{config.hxx}: in{config.hxx.in}</pre>

  <p>By default the <code>in</code> rule uses <code>$</code> as the
  substitution symbol. This can be changed using the <code>in.symbol</code>
  variable. For example:</p>

  <pre>// data.cxx.in

const char data[] = "@data@";</pre>

  <pre># buildfile

cxx{data}: in{data}
{
  in.symbol = '@'
  data = 'Hello, World!'
}</pre>

  <p>Note that the substitution symbol must be a single character.</p>

  <p>The default substitution mode is strict. In this mode every substitution
  symbol is expected to start a substitution with unresolved (to a variable
  value) names treated as errors. The double substitution symbol (for example,
  <code>$$</code>) serves as an escape sequence.</p>

  <p>The substitution mode can be relaxed using the <code>in.mode</code>
  variable. Its valid values are <code>strict</code> (default) and
  <code>lax</code>. In the lax mode a pair of substitution symbols is only
  treated as a substitution if what's between them looks like a build system
  variable name (that is, it doesn't contain spaces, etc). Everything else,
  including unterminated substitution symbols, is copied as is. Note also that
  in this mode the double substitution symbol is not treated as an escape
  sequence.</p>

  <p>The lax mode is mostly useful when trying to reuse existing
  <code>.in</code> files from other build systems, such as
  <code>autoconf</code>. Note, however, that the lax mode is still stricter
  than <code>autoconf</code>'s semantics which also leaves unresolved
  substitutions as is. For example:</p>

  <pre># buildfile

h{config}: in{config} # config.h.in
{
  in.symbol = '@'
  in.mode = lax

  CMAKE_SYSTEM_NAME = $c.target.system
  CMAKE_SYSTEM_PROCESSOR = $c.target.cpu
}</pre>

  <p>The <code>in</code> rule tracks changes to the input file as well as the
  substituted variable values and automatically regenerates the output file if
  any were detected. Substituted variable values are looked up starting from
  the target-specific variables. Typed variable values are converted to string
  using the corresponding <code>builtin.string()</code> function overload
  before substitution.</p>

  <p>While specifying substitution values as <code>buildfile</code> variables
  is usually natural, sometimes this may not be possible or convenient.
  Specifically, we may have substitution names that cannot be specified as
  <code>buildfile</code> variables, for example, because they start with an
  underscore (and are thus reserved) or because they refer to one of the
  predefined variables. Also, we may need to have different groups of
  substitution values for different cases, for example, for different
  platforms, and it would be convenient to pass such groups around as a single
  value.</p>

  <p>To support these requirements the substitution values can alternatively
  be specified as key-value pairs in the <code>in.substitutions</code>
  variable. Note that entries in this substitution map take precedence over
  the <code>buildfile</code> variables. For example:</p>

  <pre>/* config.h.in */

#define _GNU_SOURCE   @_GNU_SOURCE@
#define _POSIX_SOURCE @_POSIX_SOURCE@</pre>

  <pre># buildfile

h{config}: in{config}
{
  in.symbol = '@'
  in.mode = lax

  in.substitutions = _GNU_SOURCE@0 _POSIX_SOURCE@1
}</pre>

  <div class="note">
  <p>In the above example, the <code>@</code> characters in
  <code>in.symbol</code> and <code>in.substitutions</code> are unrelated.</p>
  </div>

  <p>Using an undefined variable in a substitution is an error. Using a
  <code>null</code> value in a substitution is also an error unless the
  fallback value is specified with the <code>in.null</code> variable. For
  example:</p>

  <pre># buildfile

h{config}: in{config}
{
  in.null = '' # Substitute null values with empty string.
}</pre>

  <div class="note">
  <p>To specify a <code>null</code> value using the
  <code>in.substitutions</code> mechanism omit the value, for example:</p>

  <pre>in.substitutions = _GNU_SOURCE</pre>
  </div>

  <p>A number of other build system modules, for example, <a
  href="https://github.com/build2/libbuild2-autoconf/"><code>autoconf</code></a>,
  <a href="#module-version"><code>version</code></a>, and <a
  href="#module-bash"><code>bash</code></a>, are based on the <code>in</code>
  module and provide extended functionality. The <code>in</code> preprocessing
  rule matches any <code>file{}</code>-based target that has the corresponding
  <code>in{}</code> prerequisite provided none of the extended rules
  match.</p>

  <h1 id="module-bash">18 <code>bash</code> Module</h1>

  <p>The <code>bash</code> build system module provides modularization support
  for <code>bash</code> scripts. It is based on the <a
  href="#module-in"><code>in</code></a> build system module and extends its
  preprocessing rule with support for <i>import substitutions</i> in the
  <code>@import&#160;&lt;module>@</code> form. During preprocessing, such
  imports are replaced with suitable <code>source</code> builtin calls. For
  example:</p>

  <pre># build/root.build

using bash</pre>

  <pre># hello/say-hello.bash

function say_hello ()
{
  echo "Hello, $1!"
}</pre>

  <pre>#!/usr/bin/env bash

# hello/hello.in

@import hello/say-hello@

say_hello 'World'</pre>

  <pre># hello/buildfile

exe{hello}: in{hello} bash{say-hello}</pre>

  <p>By default the <code>bash</code> preprocessing rule uses the lax
  substitution mode and <code>@</code> as the substitution symbol but this can
  be overridden using the standard <code>in</code> module mechanisms.</p>

  <p>In the above example, <code>say-hello.bash</code> is a <i>module</i>. By
  convention, <code>bash</code> modules have the <code>.bash</code> extension
  and we use the <code>bash{}</code> target type (defined by the
  <code>bash</code> build system module) to refer to them in buildfiles.</p>

  <p>The <code>say-hello.bash</code> module is <i>imported</i> by the
  <code>hello</code> script with the
  <code>@import&#160;hello/say-hello@</code> substitution. The <i>import
  path</i> (<code>hello/say-hello</code> in our case) is a path to the module
  file within the project. Its first component (<code>hello</code> in our
  case) must be both the project name and the top-level subdirectory within
  the project. The <code>.bash</code> module extension can be omitted. <span
  class="note">The constraint placed on the first component of the import path
  is required to implement importation of installed modules, as discussed
  below.</span></p>

  <p>During preprocessing, the import substitution will be replaced with a
  <code>source</code> builtin call and the import path resolved to one of the
  <code>bash{}</code> prerequisites from the script's dependency declaration.
  The actual module path used in <code>source</code> depends on whether the
  script is preprocessed for installation. If it's not (development build),
  then the absolute path to the module file is used. Otherwise, a path
  relative to the sourcing script's directory is derived. This allows
  installed scripts and their modules to be moved around.</p>

  <div class="note">
  <p>The derivation of the sourcing script's directory works even if the
  script is executed via a symbolic link from another directory. Implementing
  this, however, requires <code>readlink(1)</code> with support for the
  <code>-f</code> option. One notable platform that does not provide such
  <code>readlink(1)</code> by default is Mac OS. The script, however, can
  provide a suitable implementation as a function. See the <code>bash</code>
  module tests for a sample implementation of such a function.</p>
  </div>

  <p>By default, <code>bash</code> modules are installed into a subdirectory
  of the <code>bin/</code> installation directory named as the project name
  plus the <code>.bash</code> extension. For instance, in the above example,
  the script will be installed as <code>bin/hello</code> and the module as
  <code>bin/hello.bash/say-hello.bash</code> with the script sourcing the
  module relative to the <code>bin/</code> directory. Note that currently it
  is assumed the script and all its modules are installed into the same
  <code>bin/</code> directory.</p>

  <p>Naturally, modules can import other modules and modules can be packaged
  into <i>module libraries</i> and imported using the standard build system
  import mechanism. For example, we could factor the
  <code>say-hello.bash</code> module into a separate <code>libhello</code>
  project:</p>

  <pre># build/export.build

$out_root/
{
  include libhello/
}

export $src_root/libhello/$import.target</pre>

  <pre># libhello/say-hello.bash

function hello_say_hello ()
{
  echo "Hello, $1!"
}</pre>

  <p>And then import it in a module of our <code>hello</code> project:</p>

  <pre># hello/hello-world.bash.in

@import libhello/say-hello@

function hello_world ()
{
  hello_say_hello 'World'
}</pre>

  <pre>#!/usr/bin/env bash

# hello/hello.in

@import hello/hello-world@

hello_world</pre>

  <pre># hello/buildfile

import mods = libhello%bash{say-hello}

exe{hello}:        in{hello}       bash{hello-world}
bash{hello-world}: in{hello-world} $mods</pre>

  <p>The <code>bash</code> preprocessing rule also supports importation of
  installed modules by searching in the <code>PATH</code> environment
  variable.</p>

  <p>By convention, <code>bash</code> module libraries should use the
  <code>lib</code> name prefix, for example, <code>libhello</code>. If there
  is also a native library (that is, one written in C/C++) that provides the
  same functionality (or the <code>bash</code> library is a language binding
  for the said library), then it is customary to add the <code>.bash</code>
  extension to the <code>bash</code> library name, for example,
  <code>libhello.bash</code>. Note that in this case the top-level
  subdirectory within the project is expected to be called without the
  <code>bash</code> extension, for example, <code>libhello</code>.</p>

  <p>Modules can be <i>private</i> or <i>public</i>. Private modules are
  implementation details of a specific project and are not expected to be
  imported from other projects. The <code>hello/hello-world.bash.in</code>
  module above is an example of a private module. Public modules are meant to
  be used by other projects and are normally packaged into libraries, like the
  <code>libhello/say-hello.bash</code> module above.</p>

  <p>Public modules must take care to avoid name clashes. Since
  <code>bash</code> does not have a notion of namespaces, the recommended way
  is to prefix all module functions (and global variables, if any) with the
  library name (without the <code>lib</code> prefix), like in the
  <code>libhello/say-hello.bash</code> module above.</p>

  <p>While using such decorated function names can be unwieldy, it is
  relatively easy to create wrappers with shorter names and use those instead.
  For example:</p>

  <pre>@import libhello/say-hello@

function say_hello () { hello_say_hello "$@"; }</pre>

  <p>A module should normally also prevent itself from being sourced multiple
  times. The recommended way to achieve this is to begin the module with a
  <i>source guard</i>. For example:</p>

  <pre># libhello/say-hello.bash

if [ "$hello_say_hello" ]; then
  return 0
else
  hello_say_hello=true
fi

function hello_say_hello ()
{
  echo "Hello, $1!"
}</pre>

  <p>The <code>bash</code> preprocessing rule matches <code>exe{}</code>
  targets that have the corresponding <code>in{}</code> and one or more
  <code>bash{}</code> prerequisites as well as <code>bash{}</code> targets
  that have the corresponding <code>in{}</code> prerequisite (if you need to
  preprocess a script that does not depend on any modules, you can use the
  <code>in</code> module's rule).</p>

  <h1 id="json-dump">19 Appendix A &#8211; JSON Dump Format</h1>

  <p>This appendix describes the machine-readable, JSON-based build system
  state dump format that can be requested with the
  <code>--dump-format=json-v0.1</code> build system driver option (see <a
  href="b.xhtml"><code><b>b(1)</b></code></a> for details).</p>

  <p>The format is specified in terms of the serialized representation of C++
  <code>struct</code> instances. See <a href="b.xhtml#json-output">JSON
  OUTPUT</a> for details on the overall properties of this format and the
  semantics of the <code>struct</code> serialization.</p>

  <div class="note">
  <p>This format is currently unstable (thus the temporary <code>-v0.1</code>
  suffix) and may be changed in ways other than as described in <a
  href="b.xhtml#json-output">JSON OUTPUT</a>. In case of such changes the
  format version will be incremented to allow detecting incompatibilities but
  no support for older versions is guaranteed.</p>
  </div>

  <p>The build system state can be dumped after the load phase
  (<code>--dump=load</code>), once the build state has been loaded, and/or
  after the match phase (<code>--dump=match</code>), after rules have been
  matched to targets to execute the desired action. The JSON format differs
  depending on after which phase it is produced. After the load phase the
  format aims to describe the action-independent state, essentially as
  specified in the <code>buildfiles</code>. While after the match phase it
  aims to describe the state for executing the specified action, as determined
  by the rules that have been matched. The former state would be more
  appropriate, for example, for an IDE that tries to use
  <code>buildfiles</code> as project files. While the latter state could be
  used to determine the actual build graph for a certain action, for example,
  in order to infer which executable targets are considered tests by the
  <code>test</code> operation.</p>

  <p>While it's possible to dump the build state as a byproduct of executing
  an action (for example, performing an update), it's often desirable to only
  dump the build state and do it as quickly as possible. For such cases the
  recommended option combinations are as follows (see the
  <code>--load-only</code> and <code>--match-only</code> documentation for
  details):</p>

  <pre>$ b --load-only --dump=load --dump-format=json-v0.1 .../dir/

$ b --match-only --dump=match --dump-format=json-v0.1 .../dir/
$ b --match-only --dump=match --dump-format=json-v0.1 .../dir/type{name}</pre>

  <div class="note">
  <p>Note that a match dump for a large project can produce a large amount of
  data, especially for the <code>update</code> operation (tens and even
  hundreds of megabytes is not uncommon). To reduce this size it is possible
  to limit the dump to specific scopes and/or targets with the
  <code>--dump-scope</code> and <code>--dump-target</code> options.</p>
  </div>

  <p>The complete dump (that is, not of a specific scope or target) is a tree
  of nested scope objects (see <a href="#intro-dirs-scopes">Output Directories
  and Scopes</a> for background). The scope object has the serialized
  representation of the following C++ <code>struct</code> <code>scope</code>.
  It is the same for both load and match dumps except for the type of the
  <code>targets</code> member:</p>

  <pre>struct scope
{
  string           out_path;
  optional&lt;string> src_path;

  vector&lt;variable> variables; // Non-type/pattern scope variables.

  vector&lt;scope> scopes; // Immediate children.

  vector&lt;loaded_target|matched_target> targets;
};</pre>

  <p>For example (parts of the output are omitted for brevity):</p>

  <div class="note">
  <p>The actual output is produced unindented to reduce the size.</p>
  </div>

  <pre>$ cd /tmp
$ bdep new hello
$ cd hello
$ bdep new -C @gcc cc
$ b --load-only --dump=load --dump-format=json-v0.1
{
  "out_path": "",
  "variables": [ ... ],
  "scopes": [
    {
      "out_path": "/tmp/hello-gcc",
      "variables": [ ... ],
      "scopes": [
        {
          "out_path": "hello",
          "src_path": "/tmp/hello",
          "variables": [ ... ],
          "scopes": [
            {
              "out_path": "hello",
              "src_path": "/tmp/hello/hello",
              "variables": [ ... ],
              "targets": [ ... ]
            }
          ],
          "targets": [ ... ]
        }
      ],
      "targets": [ ... ]
    }
  ]
}</pre>

  <p>The <code>out_path</code> member is relative to the parent scope. It is
  empty for the special global scope, which is the root of the tree. The
  <code>src_path</code> member is absent if it is the same as
  <code>out_path</code> (in source build or scope outside of project).</p>

  <div class="note">
  <p>For the match dump, targets that have not been matched for the specified
  action are omitted.</p>
  </div>

  <p>In the load dump, the target object has the serialized representation of
  the following C++ <code>struct</code> <code>loaded_target</code>:</p>

  <pre>struct loaded_target
{
  string           name;  // Relative quoted/qualified name.
  string   display_name;  // Relative display name.
  string           type;  // Target type.
  optional&lt;string> group; // Absolute quoted/qualified group target.

  vector&lt;variable> variables; // Target variables.

  vector&lt;prerequisite> prerequisites;
};</pre>

  <p>For example (continuing with the previous <code>hello</code> setup):</p>

  <pre>{
  "out_path": "",
  "scopes": [
    {
      "out_path": "/tmp/hello-gcc",
      "scopes": [
        {
          "out_path": "hello",
          "src_path": "/tmp/hello",
          "scopes": [
            {
              "out_path": "hello",
              "src_path": "/tmp/hello/hello",
              "targets": [
                {
                  "name": "exe{hello}",
                  "display_name": "exe{hello}",
                  "type": "exe",
                  "prerequisites": [
                    {
                      "name": "cxx{hello}",
                      "type": "cxx"
                    },
                    {
                      "name": "testscript{testscript}",
                      "type": "testscript"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}</pre>

  <p>The target <code>name</code> member is the target name that is qualified
  with the extension (if applicable and known) and, if required, is quoted so
  that it can be passed back to the build system driver on the command line.
  The <code>display_name</code> member is unqualified and unquoted. Note that
  both the target <code>name</code> and <code>display_name</code> members are
  normally relative to the containing scope (if any).</p>

  <p>The prerequisite object has the serialized representation of the
  following C++ <code>struct</code> <code>prerequisite</code>:</p>

  <pre>struct prerequisite
{
  string name; // Quoted/qualified name.
  string type;
  vector&lt;variable> variables; // Prerequisite variables.
};</pre>

  <p>The prerequisite <code>name</code> member is normally relative to the
  containing scope.</p>

  <p>In the match dump, the target object has the serialized representation of
  the following C++ <code>struct</code> <code>matched_target</code>:</p>

  <pre>struct matched_target
{
  string           name;
  string   display_name;
  string           type;
  optional&lt;string> group;

  optional&lt;path> path; // Absent if not path target, not assigned.

  vector&lt;variable> variables;

  optional&lt;operation_state> outer_operation; // null if not matched.
  operation_state           inner_operation; // null if not matched.
};</pre>

  <p>For example (outer scopes removed for brevity):</p>

  <pre>$ b --match-only --dump=match --dump-format=json-v0.1
{
  "out_path": "hello",
  "src_path": "/tmp/hello/hello",
  "targets": [
    {
      "name": "/tmp/hello/hello/cxx{hello.cxx}@./",
      "display_name": "/tmp/hello/hello/cxx{hello}@./",
      "type": "cxx",
      "path": "/tmp/hello/hello/hello.cxx",
      "inner_operation": {
        "rule": "build.file",
        "state": "unchanged"
      }
    },
    {
      "name": "obje{hello.o}",
      "display_name": "obje{hello}",
      "type": "obje",
      "group": "/tmp/hello-gcc/hello/hello/obj{hello}",
      "path": "/tmp/hello-gcc/hello/hello/hello.o",
      "inner_operation": {
        "rule": "cxx.compile",
        "prerequisite_targets": [
          {
            "name": "/tmp/hello/hello/cxx{hello.cxx}@./",
            "type": "cxx"
          },
          {
            "name": "/usr/include/c++/12/h{iostream.}",
            "type": "h"
          },
          ...
        ]
      }
    },
    {
      "name": "exe{hello.}",
      "display_name": "exe{hello}",
      "type": "exe",
      "path": "/tmp/hello-gcc/hello/hello/hello",
      "inner_operation": {
        "rule": "cxx.link",
        "prerequisite_targets": [
          {
            "name": "/tmp/hello-gcc/hello/hello/obje{hello.o}",
            "type": "obje"
          }
        ]
      }
    }
  ]
}</pre>

  <p>The first four members in <code>matched_target</code> have the same
  semantics as in <code>loaded_target</code>.</p>

  <p>The <code>outer_operation</code> member is only present if the action has
  an outer operation. For example, when performing
  <code>update-for-test</code>, <code>test</code> is the outer operation while
  <code>update</code> is the inner operation.</p>

  <p>The operation state object has the serialized representation of the
  following C++ <code>struct</code> <code>operation_state</code>:</p>

  <pre>struct operation_state
{
  string rule; // null if direct recipe match.

  optional&lt;string> state; // One of unchanged|changed|group.

  vector&lt;variable> variables; // Rule variables.

  vector&lt;prerequisite_target> prerequisite_targets;
};</pre>

  <p>The <code>rule</code> member is the matched rule name. The
  <code>state</code> member is the target state, if known after match. The
  <code>prerequisite_targets</code> array is a subset of prerequisites
  resolved to targets that are in effect for this action. The matched rule may
  add additional targets, for example, dynamically extracted additional
  dependencies, like <code>/usr/include/c++/12/h{iostream.}</code> in the
  above listing.</p>

  <p>The prerequisite target object has the serialized representation of the
  following C++ <code>struct</code> <code>prerequisite_target</code>:</p>

  <pre>struct prerequisite_target
{
  string name; // Absolute quoted/qualified target name.
  string type;
  bool adhoc;
};</pre>

  <p>The <code>variables</code> array in the scope, target, prerequisite, and
  prerequisite target objects contains scope, target, prerequisite, and rule
  variables, respectively.</p>

  <p>The variable object has the serialized representation of the following
  C++ <code>struct</code> <code>variable</code>:</p>

  <pre>struct variable
{
  string           name;
  optional&lt;string> type;
  json_value       value; // null|boolean|number|string|object|array
};</pre>

  <p>For example:</p>

  <pre>{
  "out_path": "",
  "variables": [
    {
      "name": "build.show_progress",
      "type": "bool",
      "value": true
    },
    {
      "name": "build.verbosity",
      "type": "uint64",
      "value": 1
    },
    ...
  ],
  "scopes": [
    {
      "out_path": "/tmp/hello-gcc",
      "scopes": [
        {
          "out_path": "hello",
          "src_path": "/tmp/hello",
          "scopes": [
            {
              "out_path": "hello",
              "src_path": "/tmp/hello/hello",
              "variables": [
                {
                  "name": "out_base",
                  "type": "dir_path",
                  "value": "/tmp/hello-gcc/hello/hello"
                },
                {
                  "name": "src_base",
                  "type": "dir_path",
                  "value": "/tmp/hello/hello"
                },
                {
                  "name": "cxx.poptions",
                  "type": "strings",
                  "value": [
                    "-I/tmp/hello-gcc/hello",
                    "-I/tmp/hello"
                  ]
                },
                {
                  "name": "libs",
                  "value": "/tmp/hello-gcc/libhello/libhello/lib{hello}"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}</pre>

  <p>The <code>type</code> member is absent if the variable value is
  untyped.</p>

  <p>The <code>value</code> member contains the variable value in a suitable
  JSON representation. Specifically:</p>

  <ul>
  <li><code>null</code> values are represented as JSON <code>null</code>.</li>

  <li><code>bool</code> values are represented as JSON
  <code>boolean</code>.</li>

  <li><code>int64</code> and <code>uint64</code> values are represented as
  JSON <code>number</code>.</li>

  <li><code>string</code>, <code>path</code>, <code>dir_path</code> values are
  represented as JSON <code>string</code>.</li>

  <li>Untyped simple name values are represented as JSON
  <code>string</code>.</li>

  <li>Pairs of above values are represented as JSON objects with the
  <code>first</code> and <code>second</code> members corresponding to the pair
  elements.</li>

  <li>Untyped complex name values are serialized as target names and
  represented as JSON <code>string</code>.</li>

  <li>Containers of above values are represented as JSON arrays corresponding
  to the container elements.</li>

  <li>An empty value is represented as an empty JSON object if it's a typed
  pair, as an empty JSON array if it's a typed container or is untyped, and as
  an empty string otherwise.</li>
  </ul>

  <p>One expected use-case for the match dump is to determine the set of
  targets for which a given action is applicable. For example, we may want to
  determine all the executables in a project that can be tested with the
  <code>test</code> operation in order to present this list to the user in an
  IDE plugin or some such. To further illuminate the problem, consider the
  following <code>buildfile</code> which declares a number of executable
  targets, some are tests and some are not:</p>

  <pre>exe{hello1}: ... testscript # Test because of testscript prerequisite.

exe{hello2}: test = true    # Test because of test=true.

exe{hello3}: ... testscript # Not a test because of test=false.
{
  test = false
}</pre>

  <p>As can be seen, trying to infer this information is not straightforward
  and doing so manually by examining prerequisites, variables, etc., while
  possible, will be complex and likely brittle. Instead, the recommended
  approach is to use the match dump and base the decision on the
  <code>state</code> target object member. Specifically, a rule which matched
  the target but determined that nothing needs to be done for this target,
  returns the special <code>noop</code> recipe. The <code>build2</code> core
  recognizes this situation and sets such target's state to
  <code>unchanged</code> during match. Here is what the match dump will look
  like for the above three executables:</p>

  <pre>$ b --match-only --dump=match --dump-format=json-v0.1 test
{
  "out_path": "hello",
  "src_path": "/tmp/hello/hello",
  "targets": [
    {
      "name": "exe{hello1.}",
      "display_name": "exe{hello1}",
      "type": "exe",
      "path": "/tmp/hello-gcc/hello/hello/hello1",
      "inner_operation": {
        "rule": "test"
      }
    },
    {
      "name": "exe{hello2.}",
      "display_name": "exe{hello2}",
      "type": "exe",
      "path": "/tmp/hello-gcc/hello/hello/hello2",
      "inner_operation": {
        "rule": "test"
      }
    },
    {
      "name": "exe{hello3}",
      "display_name": "exe{hello3}",
      "type": "exe",
      "inner_operation": {
        "rule": "test",
        "state": "unchanged"
      }
    }
  ]
}</pre>

</div>

</body>
</html>
